@telestack/storage 1.2.1 → 1.3.1

package/README.md

@@ -1,41 +1,26 @@
 # 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.**
+Designed to be **fast, capable, and easy to use** for modern web storage workflows.
 
-## Features (Firebase Killer)
+## 🌊 Core Philosophy
+TelestackStorage is an **S3-compatible storage gateway** with metadata, search, analytics, and realtime events.
+
+## Features
 
 - 🌊 **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>
-```
+- 🚀 **Smart Upload Logic**: Uses standard uploads or resumable multipart uploads based on file size and runtime behavior.
+- 🗂️ **Rich Querying**: Multi-criteria file searching using the fluent `query()` builder.
+- 📦 **Mass Batch Operations**: Instantly delete, copy, or move multiple files in one asynchronous background request.
+- 🌐 **Zero Dependencies**, fully browser native.
+- 🧠 **Context-Aware Client**: Switch tenant/project/org defaults using `withContext(...)`.
+- 🔐 **Auth Hot-Swap**: Rotate API keys or user JWTs without rebuilding client state via `withAuth(...)`.
+- 🛡️ **Idempotent Provisioning**: `createBucketIfMissing(...)` prevents onboarding races.
 
 ---
 
-## 📦 NPM Installation
+## 📦 Installation
 
 ```bash
 npm install @telestack/storage
@@ -43,38 +28,78 @@ npm install @telestack/storage
 
 ---
 
-## Supercharged Usage
-
-### 1. Observable Uploads (Pause, Resume, Cancel)
+## 🚀 Usage
 
-Works exactly like Firebase, but intelligently handles chunking for massive files automatically.
+### 1. Initialization
+Initialize with your regional worker URL and tenant ID.
 
 ```typescript
 import { TelestackStorage } from '@telestack/storage';
 
 const storage = new TelestackStorage({
   baseUrl: 'https://api.yourdomain.com',
-  tenantId: 'tenant_123'
+  tenantId: 'your_tenant_id',
+  apiKey: 'your_api_key' // Optional
+});
+```
+
+### 2. Direct Bucket Creation (UI / Console)
+Create a project bucket directly from your UI when the user signs up.
+
+```typescript
+const storage = new TelestackStorage({
+  baseUrl: 'https://api.yourdomain.com',
+  tenantId: 'project_123',
+  orgId: 'org_456',
+  apiKey: 'your_api_key'
+});
+
+const bucket = await storage.createBucket('project-bucket');
+console.log('Created bucket ID:', bucket.bucketId);
+```
+
+### 3. Multi-Tenant DX (Context + Auth in one line)
+Use cloned clients for each workspace/user session while preserving the same API style.
+
+```typescript
+const admin = new TelestackStorage({
+  baseUrl: 'https://api.yourdomain.com',
+  tenantId: 'tenant_root',
+  projectId: 'project_default',
+  orgId: 'org_default',
+  apiKey: 'admin_key'
 });
 
-const videoBlob = new Blob([...]);
-const task = storage.ref('videos/concert.mp4').put(videoBlob, { userId: 'u123' });
+const tenantClient = admin
+  .withContext({ tenantId: 'project_789', projectId: 'project_789', orgId: 'org_456' })
+  .withAuth({ token: userJwt, apiKey: null });
+```
+
+### 4. Idempotent Bucket Provisioning (No Duplicate Errors)
+
+```typescript
+const result = await storage.createBucketIfMissing('project-bucket');
+
+if (result.created) {
+  console.log('New bucket:', result.bucketId);
+} else {
+  console.log('Bucket already exists for project:', result.projectId);
+}
+```
 
-// Listen for state changes, errors, and completion of the upload.
-const unsubscribe = task.on('state_changed', 
+### 5. Observable Uploads (Pause, Resume, Cancel)
+Works like familiar cloud-storage SDKs with resumable upload controls.
+
+```typescript
+const task = storage.ref('videos/concert.mp4').put(videoBlob);
+
+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));
-  }
+  (error) => console.error('Upload failed:', error), 
+  () => console.log('Upload completed!')
 );
 
 // Control it!
@@ -83,50 +108,24 @@ 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:
+### 6. Fluent Query Builder (Search & Filtering)
+Search by name or filter by file extension effortlessly:
 
 ```typescript
 const files = await storage.query()
-  .nameContains('report')
-  .where('project', 'Q1-Metrics')
+  .search('report')
+  .withExtension('pdf')
+  .minSize(1024 * 1024) // 1MB+
   .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' }
-]);
+## 📊 Developer Perks
+- **S3-compatible durability** with presigned URL workflows.
+- **Resumable multipart uploads** for large files.
+- **Auto-Sync**: Real-time SSE events across tabs/sessions.
 
-// Apply an immutable AWS S3 Legal Hold
-await docRef.setLegalHold('ON');
-```
+---
+*Verified production-ready for modern web storage workloads.*