TelestackStorage Web SDK

A powerful, fluent, and comprehensive client SDK for TelestackStorage. Designed to be fast, capable, and easy to use for modern web storage workflows.

🌊 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', ...)
• 🚀 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.

📦 Installation

npm install @telestack/storage

🚀 Usage

1. Initialization

Initialize with your regional worker URL and tenant ID.

import { TelestackStorage } from '@telestack/storage';

const storage = new TelestackStorage({
  baseUrl: 'https://api.yourdomain.com',
  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.

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.

const admin = new TelestackStorage({
  baseUrl: 'https://api.yourdomain.com',
  tenantId: 'tenant_root',
  projectId: 'project_default',
  orgId: 'org_default',
  apiKey: 'admin_key'
});

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)

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);
}

5. Observable Uploads (Pause, Resume, Cancel)

Works like familiar cloud-storage SDKs with resumable upload controls.

const task = storage.ref('videos/concert.mp4').put(videoBlob);

task.on('state_changed', 
  (snapshot) => {
    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!')
);

// Control it!
task.pause();
task.resume();
task.cancel(); 

6. Fluent Query Builder (Search & Filtering)

Search by name or filter by file extension effortlessly:

const files = await storage.query()
  .search('report')
  .withExtension('pdf')
  .minSize(1024 * 1024) // 1MB+
  .limit(20)
  .get();

📊 Developer Perks

• S3-compatible durability with presigned URL workflows.
• Resumable multipart uploads for large files.
• Auto-Sync: Real-time SSE events across tabs/sessions.

Verified production-ready for modern web storage workloads.