@telestack/storage 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@telestack/storage",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Official Telestack Storage Web SDK — fluent, Firebase-killer, real-time cloud storage for web apps.",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
@@ -12,6 +12,11 @@
             "require": "./dist/index.js"
         }
     },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
     "scripts": {
         "build": "tsup src/index.ts --format cjs,esm,iife --global-name TelestackStorageSetup --minify --dts --clean"
     },
@@ -23,6 +28,9 @@
         "file-upload"
     ],
     "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
     "devDependencies": {
         "@types/jsdom": "^27.0.0",
         "dotenv": "^17.3.1",
@@ -34,4 +42,4 @@
         "typescript": "^5.0.0",
         "xhr2": "^0.2.1"
     }
-}
+}

package/debug-fetch.js

@@ -1,28 +0,0 @@
-import fetch from 'node-fetch';
-
-async function testUploadUrl() {
-    try {
-        const res = await fetch('http://localhost:8787/files/upload-url', {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'X-Tenant-ID': 'test-tenant',
-                'Authorization': 'Bearer DEV_TEST_TOKEN'
-            },
-            body: JSON.stringify({
-                path: 'test.txt',
-                name: 'test.txt',
-                size: 1024,
-                contentType: 'text/plain',
-                userId: 'user-sdk-test'
-            })
-        });
-
-        const text = await res.text();
-        console.log(`Status: ${res.status}`);
-        console.log(`Body: ${text}`);
-    } catch (err) {
-        console.error('Fetch error:', err);
-    }
-}
-testUploadUrl();

package/src/BatchBuilder.ts

@@ -1,48 +0,0 @@
-import { HttpClient } from './HttpClient';
-import { BatchDeleteResult, BatchCopyResult } from './types';
-
-/**
- * Fluent builder for batch file operations.
- * Operations execute identically as single network requests over the backend API.
- * 
- * @example
- * await storage.batch().delete(['a.pdf', 'b.pdf']).run();
- * await storage.batch().copy(['a.pdf'], 'archive/').run();
- * await storage.batch().move(['a.pdf'], 'archive/').run();
- */
-export class BatchBuilder {
-    private _op: 'delete' | 'copy' | 'move' | null = null;
-    private _paths: string[] = [];
-    private _dest = '';
-
-    constructor(private readonly client: HttpClient) { }
-
-    delete(paths: string[]): this {
-        this._op = 'delete';
-        this._paths = paths;
-        return this;
-    }
-
-    copy(paths: string[], destinationPrefix: string): this {
-        this._op = 'copy';
-        this._paths = paths;
-        this._dest = destinationPrefix;
-        return this;
-    }
-
-    move(paths: string[], destinationPrefix: string): this {
-        this._op = 'move';
-        this._paths = paths;
-        this._dest = destinationPrefix;
-        return this;
-    }
-
-    async run(): Promise<BatchDeleteResult | BatchCopyResult> {
-        if (!this._op) throw new Error('No batch operation specified');
-        if (this._op === 'delete') {
-            return this.client.post<BatchDeleteResult>('/files/batch/delete', { paths: this._paths });
-        }
-        const body = { sourcePaths: this._paths, destinationPrefix: this._dest };
-        return this.client.post<BatchCopyResult>(`/files/batch/${this._op}`, body);
-    }
-}

package/src/CryptoHelper.ts

@@ -1,72 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// TelestackStorage Web SDK — CryptoHelper (E2EE)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export class CryptoHelper {
-    /**
-     * Generates a new random AES-GCM 256-bit encryption key.
-     * Returns the key as a base64 encoded string.
-     */
-    static async generateKey(): Promise<string> {
-        const key = await crypto.subtle.generateKey(
-            { name: 'AES-GCM', length: 256 },
-            true, // extractable
-            ['encrypt', 'decrypt']
-        );
-        const exported = await crypto.subtle.exportKey('raw', key);
-        return btoa(String.fromCharCode(...new Uint8Array(exported)));
-    }
-
-    /**
-     * Encrypts a Blob using AES-GCM.
-     * Prepends a random 12-byte IV to the resulting ciphertext Blob.
-     */
-    static async encrypt(blob: Blob, keyBase64: string): Promise<Blob> {
-        const key = await this._importKey(keyBase64);
-        const iv = crypto.getRandomValues(new Uint8Array(12));
-
-        const buffer = await blob.arrayBuffer();
-        const encryptedBuffer = await crypto.subtle.encrypt(
-            { name: 'AES-GCM', iv },
-            key,
-            buffer
-        );
-
-        // Prepend the 12-byte IV so we can decrypt it later
-        return new Blob([iv, encryptedBuffer], { type: 'application/octet-stream' });
-    }
-
-    /**
-     * Decrypts a Blob that was encrypted with `encrypt()`.
-     * Extracts the 12-byte IV from the front and decrypts the rest.
-     * Restores the original MIME type.
-     */
-    static async decrypt(blob: Blob, keyBase64: string, originalMimeType: string = 'application/octet-stream'): Promise<Blob> {
-        const key = await this._importKey(keyBase64);
-
-        const buffer = await blob.arrayBuffer();
-
-        // Extract the 12-byte IV from the prefix
-        const iv = buffer.slice(0, 12);
-        const ciphertext = buffer.slice(12);
-
-        const decryptedBuffer = await crypto.subtle.decrypt(
-            { name: 'AES-GCM', iv: new Uint8Array(iv) },
-            key,
-            ciphertext
-        );
-
-        return new Blob([decryptedBuffer], { type: originalMimeType });
-    }
-
-    private static async _importKey(keyBase64: string): Promise<CryptoKey> {
-        const keyBuffer = Uint8Array.from(atob(keyBase64), c => c.charCodeAt(0));
-        return crypto.subtle.importKey(
-            'raw',
-            keyBuffer,
-            { name: 'AES-GCM' },
-            false, // no need to extract it again
-            ['encrypt', 'decrypt']
-        );
-    }
-}

package/src/HttpClient.ts

@@ -1,152 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// TelestackStorage Web SDK — HTTP Client
-// ─────────────────────────────────────────────────────────────────────────────
-
-import type { TelestackConfig } from './types';
-
-export class HttpClient {
-    private baseUrl: string;
-    private tenantId: string;
-    private headers: Record<string, string>;
-
-    constructor(config: TelestackConfig) {
-        this.baseUrl = config.baseUrl.replace(/\/$/, '');
-        this.tenantId = config.tenantId;
-        this.headers = {
-            'Content-Type': 'application/json',
-            'X-Tenant-ID': config.tenantId,
-        };
-        if (config.apiKey) {
-            this.headers['X-API-Key'] = config.apiKey;
-        } else if (config.token) {
-            this.headers['Authorization'] = `Bearer ${config.token}`;
-        }
-    }
-
-    private async _fetchWithRetry(url: string | URL, options: RequestInit, retries: number = 3): Promise<Response> {
-        for (let attempt = 0; attempt <= retries; attempt++) {
-            try {
-                const res = await fetch(url, options);
-                // Retry on rate limits (429) or server errors (5xx)
-                if ((res.status === 429 || res.status >= 500) && attempt < retries) {
-                    const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
-                    console.warn(`[TelestackStorage] Network error ${res.status}. Retrying in ${delay}ms...`);
-                    await new Promise(r => setTimeout(r, delay));
-                    continue;
-                }
-                return res;
-            } catch (err: any) {
-                // Network failures (e.g. CORS, offline)
-                if (attempt < retries) {
-                    const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
-                    console.warn(`[TelestackStorage] Network un-reachable. Retrying in ${delay}ms...`);
-                    await new Promise(r => setTimeout(r, delay));
-                    continue;
-                }
-                throw err;
-            }
-        }
-        throw new Error('Unreachable code in retry logic');
-    }
-
-    async get<T>(path: string, params?: Record<string, string | undefined>): Promise<T> {
-        const url = new URL(`${this.baseUrl}${path}`);
-        if (params) {
-            Object.entries(params).forEach(([k, v]) => {
-                if (v !== undefined) url.searchParams.set(k, v);
-            });
-        }
-        const res = await this._fetchWithRetry(url.toString(), { headers: this.headers });
-        return this._handle<T>(res);
-    }
-
-    async post<T>(path: string, body?: unknown): Promise<T> {
-        const res = await this._fetchWithRetry(`${this.baseUrl}${path}`, {
-            method: 'POST',
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return this._handle<T>(res);
-    }
-
-    async patch<T>(path: string, body?: unknown): Promise<T> {
-        const res = await this._fetchWithRetry(`${this.baseUrl}${path}`, {
-            method: 'PATCH',
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return this._handle<T>(res);
-    }
-
-    async put<T>(path: string, body?: unknown): Promise<T> {
-        const res = await this._fetchWithRetry(`${this.baseUrl}${path}`, {
-            method: 'PUT',
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return this._handle<T>(res);
-    }
-
-    async delete<T>(path: string): Promise<T> {
-        const res = await this._fetchWithRetry(`${this.baseUrl}${path}`, {
-            method: 'DELETE',
-            headers: this.headers,
-        });
-        return this._handle<T>(res);
-    }
-
-    /** Upload a file binary buffer directly to a presigned S3 URL. */
-    async uploadToPresignedUrl(url: string, data: Blob | ArrayBuffer, contentType: string, onProgress?: (p: number) => void): Promise<void> {
-        const maxRetries = 3;
-        for (let attempt = 0; attempt <= maxRetries; attempt++) {
-            try {
-                await new Promise<void>((resolve, reject) => {
-                    const xhr = new XMLHttpRequest();
-                    xhr.open('PUT', url);
-                    xhr.setRequestHeader('Content-Type', contentType);
-                    if (onProgress) {
-                        xhr.upload.onprogress = (e) => {
-                            if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
-                        };
-                    }
-                    xhr.onload = () => {
-                        if (xhr.status >= 200 && xhr.status < 300) {
-                            resolve();
-                        } else if (xhr.status === 429 || xhr.status >= 500) {
-                            reject(new Error(`Retryable network error: ${xhr.status}`));
-                        } else {
-                            reject(new TelestackError(`Upload failed: ${xhr.status}`, xhr.status));
-                        }
-                    };
-                    xhr.onerror = () => reject(new Error('Retryable network error'));
-                    xhr.send(data);
-                });
-                return; // Success, exit retry loop
-            } catch (err: any) {
-                if (err instanceof TelestackError || attempt >= maxRetries) {
-                    throw err; // Fatal error or out of retries
-                }
-                const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
-                console.warn(`[TelestackStorage] Upload chunk failed. Retrying in ${delay}ms...`);
-                await new Promise(r => setTimeout(r, delay));
-            }
-        }
-    }
-
-    private async _handle<T>(res: Response): Promise<T> {
-        const json = await res.json() as any;
-        if (!res.ok) throw new TelestackError(json.error || res.statusText, res.status, json.code);
-        return json as T;
-    }
-}
-
-export class TelestackError extends Error {
-    constructor(
-        message: string,
-        public readonly status: number,
-        public readonly code?: string
-    ) {
-        super(message);
-        this.name = 'TelestackError';
-    }
-}

package/src/ImageHelper.ts

@@ -1,80 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// TelestackStorage Web SDK — ImageHelper (Compression)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export class ImageHelper {
-    /**
-     * Compresses and resizes an image Blob using the browser's native HTML5 Canvas.
-     * Only processes blobs where `type` starts with 'image/'. 
-     * If it's not an image, it returns the original blob untouched.
-     */
-    static async compress(
-        blob: Blob,
-        options: { maxWidth?: number; maxHeight?: number; quality?: number } = {}
-    ): Promise<Blob> {
-        if (!blob.type.startsWith('image/')) {
-            return blob; // Only compress images
-        }
-
-        const { maxWidth = 1920, maxHeight = 1080, quality = 0.8 } = options;
-
-        return new Promise((resolve, reject) => {
-            const img = new Image();
-            const url = URL.createObjectURL(blob);
-
-            img.onload = () => {
-                URL.revokeObjectURL(url);
-
-                let width = img.width;
-                let height = img.height;
-
-                // Calculate aspect ratio
-                if (width > maxWidth) {
-                    height = Math.round((height * maxWidth) / width);
-                    width = maxWidth;
-                }
-                if (height > maxHeight) {
-                    width = Math.round((width * maxHeight) / height);
-                    height = maxHeight;
-                }
-
-                // Create a canvas and draw the resized image
-                const canvas = document.createElement('canvas');
-                canvas.width = width;
-                canvas.height = height;
-
-                const ctx = canvas.getContext('2d');
-                if (!ctx) {
-                    return reject(new Error('Failed to get canvas 2d context for image compression'));
-                }
-
-                // Draw image on canvas
-                ctx.drawImage(img, 0, 0, width, height);
-
-                // Export to Blob
-                // Prefer webp, fallback to jpeg. Keep original type if it's png and we want transparency (advanced use case)
-                // For a general "lazy SDK" compression, outputting webp or jpeg is best.
-                const outputType = blob.type === 'image/png' ? 'image/png' : 'image/webp';
-
-                canvas.toBlob(
-                    (compressedBlob) => {
-                        if (compressedBlob) {
-                            resolve(compressedBlob);
-                        } else {
-                            reject(new Error('Canvas toBlob failed'));
-                        }
-                    },
-                    outputType,
-                    quality
-                );
-            };
-
-            img.onerror = () => {
-                URL.revokeObjectURL(url);
-                reject(new Error('Failed to load image for compression'));
-            };
-
-            img.src = url;
-        });
-    }
-}

package/src/QueryBuilder.ts

@@ -1,45 +0,0 @@
-import { HttpClient } from './HttpClient';
-import { FileMetadata, SearchResult } from './types';
-
-/**
- * Fluent builder for searching files via Metadata or Full-Text queries.
- * 
- * @example
- * const files = await storage.query()
- *   .where('project', 'Q1')
- *   .nameContains('report')
- *   .limit(10)
- *   .get();
- */
-export class QueryBuilder {
-    private _query = '';
-    private _metadata: Record<string, any> = {};
-    private _limit = 20;
-
-    constructor(private readonly client: HttpClient) { }
-
-    nameContains(text: string): this {
-        this._query = text;
-        return this;
-    }
-
-    where(key: string, value: any): this {
-        this._metadata[key] = value;
-        return this;
-    }
-
-    limit(n: number): this {
-        this._limit = n;
-        return this;
-    }
-
-    async get(): Promise<FileMetadata[]> {
-        const params: Record<string, string | undefined> = {
-            q: this._query || undefined,
-            limit: String(this._limit),
-            metadata: Object.keys(this._metadata).length > 0 ? JSON.stringify(this._metadata) : undefined,
-        };
-        const res = await this.client.get<SearchResult>('/files/search', params);
-        return res.files;
-    }
-}

package/src/StorageRef.ts

@@ -1,153 +0,0 @@
-import { CryptoHelper } from './CryptoHelper.js';
-import { HttpClient } from './HttpClient.js';
-import { FileMetadata, UploadOptions, DownloadOptions, TagSet } from './types';
-import { UploadTask } from './UploadTask';
-
-/**
- * Base abstract reference to a location in Telestack Storage.
- */
-export abstract class StorageRef {
-    constructor(
-        protected readonly client: HttpClient,
-        public readonly path: string,
-        public readonly tenantId: string,
-    ) { }
-
-    /** Navigate to a highly specific child path. Automatically infers File or Directory Ref. */
-    child(childPath: string): StorageRef {
-        const normalizedParent = this.path ? (this.path.endsWith('/') ? this.path : this.path + '/') : '';
-        const fullPath = normalizedParent + childPath.replace(/^\//, '');
-        if (fullPath.endsWith('/')) {
-            return new DirRef(this.client, fullPath, this.tenantId);
-        }
-        return new FileRef(this.client, fullPath, this.tenantId);
-    }
-}
-
-/**
- * Reference exclusively to a Directory (Prefix).
- */
-export class DirRef extends StorageRef {
-
-    /** Retrieve all files immediately within this directory prefix. */
-    async listAll(limit: number = 100): Promise<FileMetadata[]> {
-        const res = await this.client.get<{ files: FileMetadata[] }>('/files', {
-            prefix: this.path,
-            limit: String(limit),
-        });
-        return res.files;
-    }
-}
-
-/**
- * Reference exclusively to a File object.
- */
-export class FileRef extends StorageRef {
-
-    /** 
-     * Upload a File/Blob, returning an UploadTask that can be observed, paused, and cancelled.
-     * Functions identically to Firebase Storage. 
-     */
-    put(data: File | Blob, options: UploadOptions): UploadTask {
-        const size = data instanceof File ? data.size : data.size;
-        const name = data instanceof File ? data.name : (this.path.split('/').pop() || 'file');
-        const contentType = data.type || 'application/octet-stream';
-
-        return new UploadTask(this.client, this.path, data, name, contentType, options);
-    }
-
-    /** 
-     * Upload raw bytes directly.
-     */
-    putBytes(data: ArrayBuffer, contentType: string, options: UploadOptions): UploadTask {
-        const name = this.path.split('/').pop() || 'file';
-        const blob = new Blob([data], { type: contentType });
-        return new UploadTask(this.client, this.path, blob, name, contentType, options);
-    }
-
-    /** Get a time-limited presigned download URL. */
-    async getDownloadUrl(options?: DownloadOptions): Promise<string> {
-        if (options?.versionId) {
-            const res = await this.client.get<{ downloadUrl: string }>(
-                `/files/version-url/${encodeURIComponent(this.path)}`,
-                { versionId: options.versionId }
-            );
-            return res.downloadUrl;
-        }
-        const res = await this.client.get<{ downloadUrl: string }>(
-            `/files/download-url/${encodeURIComponent(this.path)}`
-        );
-        return res.downloadUrl;
-    }
-
-    /** 
-     * Securely downloads and decrypts an E2EE file entirely within the browser.
-     * Requires the exact Base64 AES-GCM key used during `put()`.
-     */
-    async getDecryptedBlob(encryptionKey: string): Promise<Blob> {
-        const downloadUrl = await this.getDownloadUrl();
-
-        // Fetch the raw encrypted bytes from the presigned URL
-        const res = await fetch(downloadUrl);
-        if (!res.ok) throw new Error(`Failed to download file from S3: ${res.status}`);
-
-        const encryptedBlob = await res.blob();
-
-        // We need the original MIME type to restore the Blob correctly.
-        // If not available on the fetch response, we can fetch metadata, but let's try to get it from the headers/metadata.
-        const metadata = await this.getMetadata();
-
-        return await CryptoHelper.decrypt(encryptedBlob, encryptionKey, metadata.content_type);
-    }
-
-    /** Get the file's metadata database record. */
-    async getMetadata(): Promise<FileMetadata> {
-        const res = await this.client.get<{ file: FileMetadata }>(
-            `/files/metadata/${encodeURIComponent(this.path)}`
-        );
-        return res.file;
-    }
-
-    /** Update custom JSON metadata on the file. */
-    async updateMetadata(metadata: Record<string, any>): Promise<FileMetadata> {
-        const res = await this.client.patch<{ file: FileMetadata }>(
-            `/files/metadata/${encodeURIComponent(this.path)}`,
-            { metadata }
-        );
-        return res.file;
-    }
-
-    /** Permanently delete this file. */
-    async delete(): Promise<void> {
-        await this.client.delete(`/files/${encodeURIComponent(this.path)}`);
-    }
-
-    // ── Enterprise ────────────────────────────────────────────────────────────
-
-    async listVersions(): Promise<{ versions: any[]; deleteMarkers: any[] }> {
-        return this.client.get(`/files/versions/${encodeURIComponent(this.path)}`);
-    }
-
-    async getVersionUrl(versionId: string): Promise<string> {
-        const res = await this.client.get<{ downloadUrl: string }>(
-            `/files/version-url/${encodeURIComponent(this.path)}`,
-            { versionId }
-        );
-        return res.downloadUrl;
-    }
-
-    async getTags(): Promise<TagSet[]> {
-        const res = await this.client.get<{ tags: TagSet[] }>(
-            `/files/tags/${encodeURIComponent(this.path)}`
-        );
-        return res.tags;
-    }
-
-    async setTags(tags: TagSet[]): Promise<void> {
-        await this.client.put(`/files/tags/${encodeURIComponent(this.path)}`, { tags });
-    }
-
-    async setLegalHold(status: 'ON' | 'OFF'): Promise<void> {
-        await this.client.post(`/files/legal-hold/${encodeURIComponent(this.path)}`, { status });
-    }
-}