@telestack/storage 1.0.0

package/src/UploadTask.ts

@@ -0,0 +1,332 @@
+import { UploadState, UploadTaskSnapshot, Observer, UploadOptions, UploadResult, FileMetadata } from './types';
+import { HttpClient } from './HttpClient';
+import { ImageHelper } from './ImageHelper';
+import { CryptoHelper } from './CryptoHelper';
+
+/**
+ * A cancellable, resumable, and observable upload task.
+ * Designed directly after Firebase Storage's UploadTask but optimized for Telestack resumable multipart pipelines.
+ */
+export class UploadTask implements Promise<UploadResult> {
+    private _state: UploadState = 'processing';
+    private _bytesTransferred = 0;
+    private _totalBytes: number = 0;
+    private _data: Blob;
+    private _observers: Observer<UploadTaskSnapshot>[] = [];
+    private _promise: Promise<UploadResult>;
+    private _resolve!: (res: UploadResult) => void;
+    private _reject!: (err: Error) => void;
+
+    // Resumable internals
+    private _uploadId?: string;
+    private _parts: { PartNumber: number; ETag: string }[] = [];
+    private _currentPartIndex = 0;
+    private _activeXhr?: XMLHttpRequest;
+    private _isResumable = false;
+
+    // Simple upload internals
+    private _simpleFileMetadata?: FileMetadata;
+
+    constructor(
+        private readonly client: HttpClient,
+        private readonly path: string,
+        data: Blob,
+        private readonly name: string,
+        private readonly contentType: string,
+        private readonly options: UploadOptions,
+    ) {
+        this._data = data;
+        this._totalBytes = data.size;
+        this._promise = new Promise((resolve, reject) => {
+            this._resolve = resolve;
+            this._reject = reject;
+        });
+
+        // Auto-start
+        this._start();
+    }
+
+    /** Register observers for state changes, errors, and completion. */
+    on(
+        event: 'state_changed',
+        nextOrObserver?: Observer<UploadTaskSnapshot> | ((snap: UploadTaskSnapshot) => void),
+        error?: (err: Error) => void,
+        complete?: () => void
+    ): () => void {
+        const observer: Observer<UploadTaskSnapshot> = typeof nextOrObserver === 'function'
+            ? { next: nextOrObserver, error, complete }
+            : (nextOrObserver || { error, complete });
+
+        this._observers.push(observer);
+
+        // Immediately emit current state
+        if (observer.next) observer.next(this.snapshot);
+
+        // Return an unsubscribe function
+        return () => {
+            this._observers = this._observers.filter(o => o !== observer);
+        };
+    }
+
+    /** Suspend the upload. Only works elegantly on resumable uploads, but supported for all. */
+    pause(): boolean {
+        if (this._state !== 'running') return false;
+        this._state = 'paused';
+        if (this._activeXhr) {
+            this._activeXhr.abort(); // abort current chunk/request
+            this._activeXhr = undefined;
+        }
+        this._notifyObservers();
+        return true;
+    }
+
+    /** Resume a paused upload. */
+    resume(): boolean {
+        if (this._state !== 'paused') return false;
+        this._state = 'running';
+        this._notifyObservers();
+
+        if (this._isResumable) {
+            this._continueResumable().catch(this._handleError);
+        } else {
+            // Simple upload must restart entirely if paused mid-flight
+            this._bytesTransferred = 0;
+            this._notifyObservers();
+            this._startSimple().catch(this._handleError);
+        }
+        return true;
+    }
+
+    /** Permanently cancel the upload, cleaning up partial server state if necessary. */
+    cancel(): boolean {
+        if (this._state === 'success' || this._state === 'error' || this._state === 'canceled') return false;
+
+        this._state = 'canceled';
+        if (this._activeXhr) {
+            this._activeXhr.abort();
+            this._activeXhr = undefined;
+        }
+
+        // Cleanup Server State
+        if (this._isResumable && this._uploadId) {
+            this.client.post('/files/resumable/abort', { path: this.path, uploadId: this._uploadId }).catch(() => { });
+        } else if (!this._isResumable && this._simpleFileMetadata) {
+            this.client.delete(`/files/${encodeURIComponent(this.path)}`).catch(() => { });
+        }
+
+        this._notifyObservers();
+        const err = new Error('Upload canceled by user');
+        err.name = 'UploadCanceled';
+        this._handleError(err);
+        return true;
+    }
+
+    get snapshot(): UploadTaskSnapshot {
+        return {
+            bytesTransferred: this._bytesTransferred,
+            totalBytes: this._totalBytes,
+            state: this._state,
+            task: this,
+        };
+    }
+
+    // Promise implementation
+    then<TResult1 = UploadResult, TResult2 = never>(
+        onfulfilled?: ((value: UploadResult) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+    ): Promise<TResult1 | TResult2> {
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<UploadResult | TResult> {
+        return this._promise.catch(onrejected);
+    }
+    finally(onfinally?: (() => void) | null): Promise<UploadResult> {
+        return this._promise.finally(onfinally);
+    }
+    readonly [Symbol.toStringTag] = "UploadTask";
+
+    // ── Internal Upload Logic ──────────────────────────────────────────────
+
+    private async _start() {
+        try {
+            // Processing Pipeline
+            if (this.options.compressImage && this._data.type.startsWith('image/')) {
+                this._data = await ImageHelper.compress(this._data, this.options.compressImage);
+            }
+
+            if (this.options.encryptionKey) {
+                this._data = await CryptoHelper.encrypt(this._data, this.options.encryptionKey);
+            }
+
+            this._totalBytes = this._data.size;
+
+            // If the upload was canceled during the processing delay, halt.
+            if (this._state !== 'processing') return;
+
+            this._state = 'running';
+            this._notifyObservers();
+
+            const MULTIPART_THRESHOLD = 50 * 1024 * 1024; // 50MB
+            this._isResumable = this._totalBytes >= MULTIPART_THRESHOLD;
+
+            if (this._isResumable) {
+                await this._startResumable();
+            } else {
+                await this._startSimple();
+            }
+        } catch (err: any) {
+            this._handleError(err);
+        }
+    }
+
+    private async _startSimple() {
+        // Init
+        const res = await this.client.post<{ uploadUrl: string; file: FileMetadata }>('/files/upload-url', {
+            path: this.path, name: this.name, size: this._totalBytes, contentType: this.contentType,
+            userId: this.options.userId, metadata: this.options.metadata,
+        });
+
+        this._simpleFileMetadata = res.file;
+        if (this._state !== 'running') return; // aborted during init
+
+        // Upload
+        const xhr = new XMLHttpRequest();
+        this._activeXhr = xhr;
+
+        await new Promise<void>((resolve, reject) => {
+            xhr.open('PUT', res.uploadUrl);
+            xhr.setRequestHeader('Content-Type', this.contentType);
+
+            xhr.upload.onprogress = (e) => {
+                if (e.lengthComputable && this._state === 'running') {
+                    this._bytesTransferred = e.loaded;
+                    this._notifyObservers();
+                }
+            };
+
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) resolve();
+                else reject(new Error(`Upload failed: ${xhr.status} ${xhr.responseText}`));
+            };
+            xhr.onerror = () => reject(new Error('Network error during upload'));
+            xhr.onabort = () => reject(new Error('Upload aborted'));
+
+            xhr.send(this._data);
+        });
+
+        this._activeXhr = undefined;
+        if (this._state !== 'running') return;
+
+        // Complete
+        await this.client.post('/files/complete-upload', { path: this.path });
+
+        this._bytesTransferred = this._totalBytes;
+        this._state = 'success';
+        this._notifyObservers();
+        this._resolve({ file: res.file, resumable: false });
+    }
+
+    private async _startResumable() {
+        // 1. Init Session
+        const init = await this.client.post<{ uploadId: string; file: FileMetadata }>('/files/resumable/init', {
+            path: this.path, name: this.name, size: this._totalBytes, contentType: this.contentType,
+            userId: this.options.userId, metadata: this.options.metadata,
+        });
+
+        this._uploadId = init.uploadId;
+        this._simpleFileMetadata = init.file;
+
+        await this._continueResumable();
+    }
+
+    private async _continueResumable() {
+        if (!this._uploadId || !this._simpleFileMetadata) return;
+
+        const chunkSize = this.options.chunkSize ?? 10 * 1024 * 1024;
+        const totalParts = Math.ceil(this._totalBytes / chunkSize);
+
+        try {
+            while (this._currentPartIndex < totalParts) {
+                if (this._state !== 'running') return; // Paused or Canceled
+
+                const start = this._currentPartIndex * chunkSize;
+                const end = Math.min(start + chunkSize, this._totalBytes);
+                const chunk = this._data.slice(start, end);
+
+                // Get part URL
+                const partRes = await this.client.post<{ uploadUrl: string }>('/files/resumable/part-url', {
+                    path: this.path, uploadId: this._uploadId, partNumber: this._currentPartIndex + 1
+                });
+
+                if (this._state !== 'running') return;
+
+                // Upload Chunk
+                const etag = await this._uploadChunkWithProgress(partRes.uploadUrl, chunk, start);
+
+                this._parts.push({ PartNumber: this._currentPartIndex + 1, ETag: etag });
+                this._currentPartIndex++;
+                this._bytesTransferred = Math.min(this._currentPartIndex * chunkSize, this._totalBytes);
+                this._notifyObservers();
+            }
+
+            if (this._state === 'running') {
+                // Complete
+                await this.client.post('/files/resumable/complete', {
+                    path: this.path, uploadId: this._uploadId, parts: this._parts
+                });
+
+                this._state = 'success';
+                this._notifyObservers();
+                this._resolve({ file: this._simpleFileMetadata, resumable: true });
+            }
+        } catch (err: any) {
+            if (err.message === 'Upload aborted') return; // Gracefully handled by pause/cancel
+            this._handleError(err);
+        }
+    }
+
+    private _uploadChunkWithProgress(url: string, chunk: Blob, startOffset: number): Promise<string> {
+        return new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            this._activeXhr = xhr;
+
+            xhr.open('PUT', url);
+            xhr.setRequestHeader('Content-Type', this.contentType);
+
+            xhr.upload.onprogress = (e) => {
+                if (e.lengthComputable && this._state === 'running') {
+                    this._bytesTransferred = startOffset + e.loaded;
+                    this._notifyObservers();
+                }
+            };
+
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    const etag = xhr.getResponseHeader('ETag') || '';
+                    resolve(etag.replace(/"/g, ''));
+                } else reject(new Error(`Part upload failed: ${xhr.status}`));
+            };
+            xhr.onerror = () => reject(new Error('Network error during part upload'));
+            xhr.onabort = () => reject(new Error('Upload aborted'));
+
+            xhr.send(chunk);
+        });
+    }
+
+    private _notifyObservers() {
+        const snap = this.snapshot;
+        this._observers.forEach(obs => {
+            if (snap.state === 'success' && obs.complete) obs.complete();
+            else if (obs.next) obs.next(snap);
+        });
+    }
+
+    private _handleError = (err: Error) => {
+        if (this._state === 'canceled') return; // Error naturally triggered via abort
+        this._state = 'error';
+        this._activeXhr = undefined;
+        this._notifyObservers();
+        this._observers.forEach(o => o.error?.(err));
+        this._reject(err);
+    }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// TelestackStorage Web SDK — Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+export { TelestackStorage } from './TelestackStorage.js';
+export { StorageRef, FileRef, DirRef } from './StorageRef.js';
+export { UploadTask } from './UploadTask.js';
+export { BatchBuilder } from './BatchBuilder.js';
+export { QueryBuilder } from './QueryBuilder.js';
+export { HttpClient, TelestackError } from './HttpClient.js';
+export { CryptoHelper } from './CryptoHelper.js';
+export { ImageHelper } from './ImageHelper.js';
+
+export type {
+    TelestackConfig,
+    FileMetadata,
+    UploadOptions,
+    DownloadOptions,
+    ListOptions,
+    SearchOptions,
+    SearchResult,
+    UploadResult,
+    UploadState,
+    UploadTaskSnapshot,
+    Observer,
+    TagSet,
+    BatchCopyResult,
+    BatchDeleteResult,
+} from './types';

package/src/types.ts

@@ -0,0 +1,91 @@
+export interface TelestackConfig {
+    baseUrl: string;
+    apiKey?: string;
+    token?: string;
+    tenantId: string;
+    defaultUploadOptions?: Partial<UploadOptions>;
+}
+
+export interface FileMetadata {
+    id: string;
+    tenant_id: string;
+    path: string;
+    name: string;
+    size: number;
+    content_type: string;
+    owner_id: string;
+    status: 'pending' | 'active' | 'deleted';
+    metadata: Record<string, any>;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface UploadOptions {
+    tenantId?: string;
+    userId: string;
+    metadata?: Record<string, any>;
+    chunkSize?: number; // default 10MB
+    encryptionKey?: string; // Base64 AES-GCM key for E2EE
+    compressImage?: {
+        maxWidth?: number;
+        maxHeight?: number;
+        quality?: number; // 0.0 to 1.0
+    };
+}
+
+export interface DownloadOptions {
+    versionId?: string;
+}
+
+export interface ListOptions {
+    prefix?: string;
+    limit?: number;
+}
+
+export interface SearchOptions {
+    query?: string;
+    metadata?: Record<string, any>;
+    limit?: number;
+}
+
+export interface SearchResult {
+    success: boolean;
+    files: FileMetadata[];
+}
+
+export interface UploadResult {
+    file: FileMetadata;
+    resumable: boolean;
+}
+
+export interface BatchDeleteResult {
+    success: boolean;
+    deletedCount: number;
+    errors: any[];
+}
+
+export interface BatchCopyResult {
+    success: boolean;
+    results: any[];
+}
+
+export interface TagSet {
+    Key: string;
+    Value: string;
+}
+
+/** Upload State Enum exactly like Firebase */
+export type UploadState = 'processing' | 'running' | 'paused' | 'success' | 'error' | 'canceled';
+
+export interface UploadTaskSnapshot {
+    bytesTransferred: number;
+    totalBytes: number;
+    state: UploadState;
+    task: import('./UploadTask').UploadTask;
+}
+
+export type Observer<T> = {
+    next?: (value: T) => void;
+    error?: (error: Error) => void;
+    complete?: () => void;
+};

package/test-e2e.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsdom_1 = require("jsdom");
+const dom = new jsdom_1.JSDOM();
+global.XMLHttpRequest = dom.window.XMLHttpRequest;
+global.File = dom.window.File;
+global.Blob = dom.window.Blob;
+const jose_1 = require("jose");
+const index_js_1 = require("./dist/index.js");
+const TENANT_ID = 'test-tenant';
+const USER_ID = 'user-sdk-test';
+const JWT_SECRET = new TextEncoder().encode('telestack-super-secret-key-1234567890');
+async function getAuthToken() {
+    return await new jose_1.SignJWT({
+        sub: USER_ID,
+        tenant_id: TENANT_ID,
+        role: 'admin',
+        email: 'test@example.com'
+    })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setIssuedAt()
+        .setIssuer('telestack-auth')
+        .setAudience('telestack-storage')
+        .setExpirationTime('2h')
+        .sign(JWT_SECRET);
+}
+async function runSdkTests() {
+    const token = await getAuthToken();
+    const storage = new index_js_1.TelestackStorage({
+        baseUrl: 'http://localhost:8787',
+        tenantId: TENANT_ID,
+        token: token,
+    });
+    console.log('🧪 Starting Telestack Storage Web SDK Comprehensive Tests...\n');
+    try {
+        // --- 1. Simple Upload ---
+        console.log('1️⃣ Testing Simple Upload (UploadTask)...');
+        const simpleContent = new TextEncoder().encode('Hello Telestack SDK Simple Test!');
+        const simpleBlob = new Blob([simpleContent], { type: 'text/plain' });
+        const simpleTask = storage.ref('sdk-tests/simple.txt').put(simpleBlob, { userId: USER_ID });
+        await new Promise((resolve, reject) => {
+            simpleTask.on('state_changed', (snap) => console.log(`   Progress: ${(snap.bytesTransferred / snap.totalBytes * 100).toFixed(0)}%`), (err) => reject(err), () => resolve());
+        });
+        console.log('✅ Simple Upload Completed\n');
+        // --- 2. Querying Metadata ---
+        console.log('2️⃣ Testing Query Builder...');
+        const queryResults = await storage.query()
+            .nameContains('simple.txt')
+            .limit(5)
+            .get();
+        console.log(`   Found ${queryResults.length} files matching query.`);
+        if (queryResults.length === 0)
+            throw new Error('Query failed to find uploaded file.');
+        console.log('✅ Query Builder Passed\n');
+        // --- 3. Directory Listing ---
+        console.log('3️⃣ Testing Directory Refs (listAll)...');
+        const dirFiles = await storage.dir('sdk-tests/').listAll();
+        console.log(`   Found ${dirFiles.length} files in directory.`);
+        console.log('✅ Directory Listing Passed\n');
+        // --- 4. Resumable Upload (Chunking) ---
+        console.log('4️⃣ Testing Resumable Upload (Chunks + Pause/Resume)...');
+        // Generate a 60MB string dynamically for testing multipart chunking
+        const bigContentSize = 60 * 1024 * 1024;
+        const bigArray = new Uint8Array(bigContentSize);
+        bigArray.fill(65); // Fill with 'A'
+        const bigBlob = new Blob([bigArray], { type: 'application/zip' });
+        const resumableTask = storage.ref('sdk-tests/big-resumable.bin').put(bigBlob, {
+            userId: USER_ID,
+            chunkSize: 20 * 1024 * 1024, // 20MB chunks
+            metadata: { test: 'sdk-resumable' }
+        });
+        await new Promise((resolve, reject) => {
+            let paused = false;
+            resumableTask.on('state_changed', (snap) => {
+                console.log(`   Resumable Progress: ${(snap.bytesTransferred / snap.totalBytes * 100).toFixed(0)}% (${snap.bytesTransferred} bytes)`);
+                // Pause halfway
+                if (snap.bytesTransferred > 20 * 1024 * 1024 && !paused) {
+                    paused = true;
+                    console.log('   ⏸️ Pausing upload...');
+                    resumableTask.pause();
+                    setTimeout(() => {
+                        console.log('   ▶️ Resuming upload...');
+                        resumableTask.resume();
+                    }, 2000);
+                }
+            }, (err) => reject(err), () => resolve());
+        });
+        console.log('✅ Resumable Multipart Upload Passed\n');
+        // --- 5. Download URL & Metadata CRUD ---
+        console.log('5️⃣ Testing Download URL & Metadata Update...');
+        const simpleRef = storage.ref('sdk-tests/simple.txt');
+        const url = await simpleRef.getDownloadUrl();
+        console.log('   Download URL:', url.substring(0, 50) + '...');
+        await simpleRef.updateMetadata({ newField: 'UpdatedSDKMetadata' });
+        const updatedMeta = await simpleRef.getMetadata();
+        if (updatedMeta.metadata.newField !== 'UpdatedSDKMetadata')
+            throw new Error('Metadata update failed');
+        console.log('✅ Metadata Update Passed\n');
+        // --- 5.5 End-to-End Encryption (E2EE) ---
+        console.log('🔒 Testing End-to-End Encryption (E2EE)...');
+        const { CryptoHelper } = require('./dist/index.js');
+        const e2eKey = await CryptoHelper.generateKey();
+        const secretContent = new TextEncoder().encode('Super Secret Confidential Data!');
+        const secretBlob = new Blob([secretContent], { type: 'text/plain' });
+        const secureTask = storage.ref('sdk-tests/secure-data.txt').put(secretBlob, {
+            userId: USER_ID,
+            encryptionKey: e2eKey
+        });
+        await new Promise((resolve, reject) => {
+            secureTask.on('state_changed', () => { }, (err) => reject(err), () => resolve());
+        });
+        // Verify we can fetch and decrypt it successfully
+        console.log('   Downloading and decrypting E2EE blob...');
+        const decryptedBlob = await storage.ref('sdk-tests/secure-data.txt').getDecryptedBlob(e2eKey);
+        const decryptedText = await decryptedBlob.text();
+        if (decryptedText !== 'Super Secret Confidential Data!') {
+            throw new Error('E2EE Decryption failed or ciphertext mismatch');
+        }
+        console.log('✅ End-to-End Encryption (E2EE) Passed\n');
+        // --- 6. Batch Operations ---
+        console.log('6️⃣ Testing Batch/Mass Operations over network...');
+        console.log('   Moving files to /archive...');
+        const moveRes = await storage.batch()
+            .move(['sdk-tests/simple.txt', 'sdk-tests/big-resumable.bin'], 'sdk-archive/tests/')
+            .run();
+        if (!moveRes.success)
+            throw new Error('Batch Move failed');
+        console.log('✅ Batch Move Passed\n');
+        // --- Final Cleanup ---
+        console.log('🧹 Formatting cleanup (Batch Delete)...');
+        const finalDel = await storage.batch()
+            .delete(['sdk-archive/tests/simple.txt', 'sdk-archive/tests/big-resumable.bin', 'sdk-tests/secure-data.txt'])
+            .run();
+        console.log(`   Deleted ${finalDel.deletedCount} files.`);
+        console.log('\n🎉 ALL WEB SDK TESTS PASSED SUCCESSFULLY! The SDK is robust.');
+    }
+    catch (err) {
+        console.error('\n❌ WEB SDK TEST FAILED:', err.message || err);
+        process.exit(1);
+    }
+}
+runSdkTests();