@telestack/storage 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# TelestackStorage Web SDK
+
+A powerful, fluent, and comprehensive client SDK for TelestackStorage. 
+Designed expressly to be **faster, more capable, and easier to use than Firebase Storage or Appwrite Storage.**
+
+## Features (Firebase Killer)
+
+- 🌊 **Fluent Directory & File References** (`storage.ref('path').child('video.mp4')`)
+- 📈 **Observable Upload Tasks**: Built directly around progress observers, pausing, resuming, and canceling `uploadTask.on('state_changed', ...)`
+- 🚀 **Automatic Chunked Resumable Uploads**: Flawlessly transitions streams to chunked multipart uploads (perfect for poor connectivity)
+- 🗂️ **Rich Querying**: Full-text and metadata array queries (`query().where('uid', '123').get()`)
+- 📦 **Mass Batch Operations**: Instantly delete, copy, or move multiple files over network in _one_ request.
+- 🛡️ **Enterprise Ready**: Storage Versioning, Legal holds, and Object Tagging out of the box.
+- 🌐 **Zero Dependencies**, fully browser native `fetch` and `XMLHttpRequest`.
+
+---
+
+## 🚀 Standalone Installation (CDN)
+
+You can use Telestack Storage as a completely standalone library directly in HTML:
+
+```html
+<script src="https://unpkg.com/@telestack/storage/dist/index.global.js"></script>
+<script>
+  // The SDK is exposed globally as `TelestackStorageSetup.TelestackStorage`
+  const { TelestackStorage } = window.TelestackStorageSetup;
+
+  const storage = new TelestackStorage({
+    baseUrl: 'https://storage.yourdomain.com',
+    tenantId: 'your_tenant_id',
+    apiKey: 'your_api_key'
+  });
+</script>
+```
+
+---
+
+## 📦 NPM Installation
+
+```bash
+npm install @telestack/storage
+```
+
+---
+
+## Supercharged Usage
+
+### 1. Observable Uploads (Pause, Resume, Cancel)
+
+Works exactly like Firebase, but intelligently handles chunking for massive files automatically.
+
+```typescript
+import { TelestackStorage } from '@telestack/storage';
+
+const storage = new TelestackStorage({
+  baseUrl: 'https://api.yourdomain.com',
+  tenantId: 'tenant_123'
+});
+
+const videoBlob = new Blob([...]);
+const task = storage.ref('videos/concert.mp4').put(videoBlob, { userId: 'u123' });
+
+// Listen for state changes, errors, and completion of the upload.
+const unsubscribe = task.on('state_changed', 
+  (snapshot) => {
+    // Observers receive exact byte counts and state ('running', 'paused', etc.)
+    const progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
+    console.log(`Upload is ${progress}% done. State: ${snapshot.state}`);
+  }, 
+  (error) => {
+    console.error('Upload failed:', error);
+  }, 
+  () => {
+    console.log('Upload completed successfully!');
+    // Get the download URL directly from the ref
+    task.snapshot.task.ref.getDownloadUrl().then(url => console.log('File available at:', url));
+  }
+);
+
+// Control it!
+task.pause();
+task.resume();
+task.cancel(); 
+```
+
+### 2. Fluent Query Builder (Search & Filtering)
+
+No more paginating basic lists manually to find a single file. Search by name or filter by metadata effortlessly:
+
+```typescript
+const files = await storage.query()
+  .nameContains('report')
+  .where('project', 'Q1-Metrics')
+  .limit(20)
+  .get();
+```
+
+### 3. Server-Side Batch Operations
+
+Perform mass directory operations securely with a single API call (executed asynchronously on Cloudflare):
+
+```typescript
+// Delete multiple files instantly
+await storage.batch()
+  .delete(['old/1.png', 'old/2.png'])
+  .run();
+
+// Move/Rename hundreds of files effortlessly
+await storage.batch()
+  .move(['docs/a.pdf', 'docs/b.pdf'], 'archive/')
+  .run();
+```
+
+### 4. Enterprise Compliance Features
+
+Storage versioning, tagging & immutable legal holds are built natively into the fluent refs:
+
+```typescript
+const docRef = storage.ref('critical-contracts/nda.pdf');
+
+// Retrieve a previously overwritten historical version
+const url = await docRef.getVersionUrl('v3_abc123');
+
+// S3 object tags for billing and automation
+await docRef.setTags([
+  { Key: 'SecurityLevel', Value: 'Confidential' },
+  { Key: 'Department', Value: 'Legal' }
+]);
+
+// Apply an immutable AWS S3 Legal Hold
+await docRef.setLegalHold('ON');
+```

package/debug-fetch.js

@@ -0,0 +1,28 @@
+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/dist/index.d.mts

@@ -0,0 +1,329 @@
+declare class HttpClient {
+    private baseUrl;
+    private tenantId;
+    private headers;
+    constructor(config: TelestackConfig);
+    private _fetchWithRetry;
+    get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    /** Upload a file binary buffer directly to a presigned S3 URL. */
+    uploadToPresignedUrl(url: string, data: Blob | ArrayBuffer, contentType: string, onProgress?: (p: number) => void): Promise<void>;
+    private _handle;
+}
+declare class TelestackError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+/**
+ * A cancellable, resumable, and observable upload task.
+ * Designed directly after Firebase Storage's UploadTask but optimized for Telestack resumable multipart pipelines.
+ */
+declare class UploadTask implements Promise<UploadResult> {
+    private readonly client;
+    private readonly path;
+    private readonly name;
+    private readonly contentType;
+    private readonly options;
+    private _state;
+    private _bytesTransferred;
+    private _totalBytes;
+    private _data;
+    private _observers;
+    private _promise;
+    private _resolve;
+    private _reject;
+    private _uploadId?;
+    private _parts;
+    private _currentPartIndex;
+    private _activeXhr?;
+    private _isResumable;
+    private _simpleFileMetadata?;
+    constructor(client: HttpClient, path: string, data: Blob, name: string, contentType: string, options: UploadOptions);
+    /** 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;
+    /** Suspend the upload. Only works elegantly on resumable uploads, but supported for all. */
+    pause(): boolean;
+    /** Resume a paused upload. */
+    resume(): boolean;
+    /** Permanently cancel the upload, cleaning up partial server state if necessary. */
+    cancel(): boolean;
+    get snapshot(): UploadTaskSnapshot;
+    then<TResult1 = UploadResult, TResult2 = never>(onfulfilled?: ((value: UploadResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<UploadResult | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<UploadResult>;
+    readonly [Symbol.toStringTag] = "UploadTask";
+    private _start;
+    private _startSimple;
+    private _startResumable;
+    private _continueResumable;
+    private _uploadChunkWithProgress;
+    private _notifyObservers;
+    private _handleError;
+}
+
+interface TelestackConfig {
+    baseUrl: string;
+    apiKey?: string;
+    token?: string;
+    tenantId: string;
+    defaultUploadOptions?: Partial<UploadOptions>;
+}
+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;
+}
+interface UploadOptions {
+    tenantId?: string;
+    userId: string;
+    metadata?: Record<string, any>;
+    chunkSize?: number;
+    encryptionKey?: string;
+    compressImage?: {
+        maxWidth?: number;
+        maxHeight?: number;
+        quality?: number;
+    };
+}
+interface DownloadOptions {
+    versionId?: string;
+}
+interface ListOptions {
+    prefix?: string;
+    limit?: number;
+}
+interface SearchOptions {
+    query?: string;
+    metadata?: Record<string, any>;
+    limit?: number;
+}
+interface SearchResult {
+    success: boolean;
+    files: FileMetadata[];
+}
+interface UploadResult {
+    file: FileMetadata;
+    resumable: boolean;
+}
+interface BatchDeleteResult {
+    success: boolean;
+    deletedCount: number;
+    errors: any[];
+}
+interface BatchCopyResult {
+    success: boolean;
+    results: any[];
+}
+interface TagSet {
+    Key: string;
+    Value: string;
+}
+/** Upload State Enum exactly like Firebase */
+type UploadState = 'processing' | 'running' | 'paused' | 'success' | 'error' | 'canceled';
+interface UploadTaskSnapshot {
+    bytesTransferred: number;
+    totalBytes: number;
+    state: UploadState;
+    task: UploadTask;
+}
+type Observer<T> = {
+    next?: (value: T) => void;
+    error?: (error: Error) => void;
+    complete?: () => void;
+};
+
+/**
+ * Base abstract reference to a location in Telestack Storage.
+ */
+declare abstract class StorageRef {
+    protected readonly client: HttpClient;
+    readonly path: string;
+    readonly tenantId: string;
+    constructor(client: HttpClient, path: string, tenantId: string);
+    /** Navigate to a highly specific child path. Automatically infers File or Directory Ref. */
+    child(childPath: string): StorageRef;
+}
+/**
+ * Reference exclusively to a Directory (Prefix).
+ */
+declare class DirRef extends StorageRef {
+    /** Retrieve all files immediately within this directory prefix. */
+    listAll(limit?: number): Promise<FileMetadata[]>;
+}
+/**
+ * Reference exclusively to a File object.
+ */
+declare 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;
+    /**
+     * Upload raw bytes directly.
+     */
+    putBytes(data: ArrayBuffer, contentType: string, options: UploadOptions): UploadTask;
+    /** Get a time-limited presigned download URL. */
+    getDownloadUrl(options?: DownloadOptions): Promise<string>;
+    /**
+     * Securely downloads and decrypts an E2EE file entirely within the browser.
+     * Requires the exact Base64 AES-GCM key used during `put()`.
+     */
+    getDecryptedBlob(encryptionKey: string): Promise<Blob>;
+    /** Get the file's metadata database record. */
+    getMetadata(): Promise<FileMetadata>;
+    /** Update custom JSON metadata on the file. */
+    updateMetadata(metadata: Record<string, any>): Promise<FileMetadata>;
+    /** Permanently delete this file. */
+    delete(): Promise<void>;
+    listVersions(): Promise<{
+        versions: any[];
+        deleteMarkers: any[];
+    }>;
+    getVersionUrl(versionId: string): Promise<string>;
+    getTags(): Promise<TagSet[]>;
+    setTags(tags: TagSet[]): Promise<void>;
+    setLegalHold(status: 'ON' | 'OFF'): Promise<void>;
+}
+
+/**
+ * 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();
+ */
+declare class BatchBuilder {
+    private readonly client;
+    private _op;
+    private _paths;
+    private _dest;
+    constructor(client: HttpClient);
+    delete(paths: string[]): this;
+    copy(paths: string[], destinationPrefix: string): this;
+    move(paths: string[], destinationPrefix: string): this;
+    run(): Promise<BatchDeleteResult | BatchCopyResult>;
+}
+
+/**
+ * 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();
+ */
+declare class QueryBuilder {
+    private readonly client;
+    private _query;
+    private _metadata;
+    private _limit;
+    constructor(client: HttpClient);
+    nameContains(text: string): this;
+    where(key: string, value: any): this;
+    limit(n: number): this;
+    get(): Promise<FileMetadata[]>;
+}
+
+/**
+ * TelestackStorage — The main SDK client.
+ * More comprehensive and fluent than Firebase/Appwrite Storage.
+ *
+ * @example
+ * ```ts
+ * const storage = new TelestackStorage({
+ *   baseUrl: 'https://storage.yourdomain.com',
+ *   tenantId: 'your_tenant_id',
+ *   apiKey: 'tk_your_api_key',
+ * });
+ *
+ * // Upload with progress, pause, and resume
+ * const task = storage.ref('videos/demo.mp4').put(videoBlob);
+ * task.on('state_changed',
+ *   (snap) => console.log((snap.bytesTransferred / snap.totalBytes) * 100 + '%'),
+ *   (err) => console.error(err),
+ *   () => console.log('Done!')
+ * );
+ *
+ * // Later...
+ * task.pause();
+ * task.resume();
+ * ```
+ */
+declare class TelestackStorage {
+    private readonly config;
+    private readonly http;
+    readonly tenantId: string;
+    constructor(config: TelestackConfig);
+    /** Get a highly-fluent reference to a specific file. */
+    ref(path: string): FileRef;
+    /** Get a highly-fluent reference to a directory/prefix. */
+    dir(path: string): DirRef;
+    /** Helper: List files for the entire bucket/tenant or specific prefix. */
+    list(options?: ListOptions): Promise<FileMetadata[]>;
+    /** Get a fluent batch operation builder for mass-mutations over the network. */
+    batch(): BatchBuilder;
+    /** Get a fluent query builder for metadata and full-text search. */
+    query(): QueryBuilder;
+    /** Generate a new API key (admin only). The key is shown only once. */
+    generateApiKey(name?: string): Promise<{
+        apiKey: string;
+        message: string;
+    }>;
+    /** Revoke an API key by its ID. */
+    revokeApiKey(keyId: string): Promise<void>;
+    /** Get S3 bucket configuration details. */
+    getBucketInfo(): Promise<any>;
+}
+
+declare class CryptoHelper {
+    /**
+     * Generates a new random AES-GCM 256-bit encryption key.
+     * Returns the key as a base64 encoded string.
+     */
+    static generateKey(): Promise<string>;
+    /**
+     * Encrypts a Blob using AES-GCM.
+     * Prepends a random 12-byte IV to the resulting ciphertext Blob.
+     */
+    static encrypt(blob: Blob, keyBase64: string): Promise<Blob>;
+    /**
+     * 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 decrypt(blob: Blob, keyBase64: string, originalMimeType?: string): Promise<Blob>;
+    private static _importKey;
+}
+
+declare 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 compress(blob: Blob, options?: {
+        maxWidth?: number;
+        maxHeight?: number;
+        quality?: number;
+    }): Promise<Blob>;
+}
+
+export { BatchBuilder, type BatchCopyResult, type BatchDeleteResult, CryptoHelper, DirRef, type DownloadOptions, type FileMetadata, FileRef, HttpClient, ImageHelper, type ListOptions, type Observer, QueryBuilder, type SearchOptions, type SearchResult, StorageRef, type TagSet, type TelestackConfig, TelestackError, TelestackStorage, type UploadOptions, type UploadResult, type UploadState, UploadTask, type UploadTaskSnapshot };