@telestack/storage 1.2.0 → 1.3.1

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 declare class HttpClient {
-    private baseUrl;
+    readonly baseUrl: string;
     private tenantId;
     private headers;
+    readonly defaultUploadOptions?: Partial<UploadOptions>;
     constructor(config: TelestackConfig);
     private _fetchWithRetry;
     get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
@@ -13,44 +14,92 @@ declare class HttpClient {
     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.
+ * A cancellable, pausable, and observable upload task.
+ * Modelled after Firebase Storage UploadTask — familiar API, powered by Telestack.
+ *
+ * @example
+ * ```ts
+ * const task = storage.ref('photos/sunset.jpg').put(file, { userId: 'u_123' });
+ *
+ * task.on('state_changed',
+ *   snap => console.log(`${Math.round(snap.bytesTransferred / snap.totalBytes * 100)}%`),
+ *   err  => console.error('Upload failed:', err),
+ *   ()   => console.log('Upload complete!')
+ * );
+ *
+ * // Pause / Resume
+ * task.pause();
+ * setTimeout(() => task.resume(), 2000);
+ *
+ * // Await as a promise
+ * const result = await task;
+ * console.log('File ID:', result.file_id);
+ * ```
  */
 declare class UploadTask implements Promise<UploadResult> {
     private readonly client;
     private readonly path;
+    /** Filename */
     private readonly name;
     private readonly contentType;
     private readonly options;
+    /** Tenant ID, inherited from SDK config */
+    private readonly tenantId;
+    /** Current upload lifecycle state. */
     private _state;
+    /** Bytes confirmed as uploaded so far. */
     private _bytesTransferred;
+    /** Final payload size after optional compression/encryption. */
     private _totalBytes;
+    /** Mutable upload payload (can change after preprocessing). */
     private _data;
+    /** Observer registry for `state_changed` notifications. */
     private _observers;
+    /** Promise facade for `await task`. */
     private _promise;
+    /** Internal promise resolve hook. */
     private _resolve;
+    /** Internal promise reject hook. */
     private _reject;
+    /** Multipart session id returned by the worker. */
     private _uploadId?;
+    /** File record id in metadata DB. */
+    private _fileId?;
+    /** Current version id in metadata DB (simple uploads). */
+    private _versionId?;
+    /** Object-store key generated by worker. */
+    private _storageKey?;
+    /** Uploaded multipart part list used for complete call. */
     private _parts;
+    /** Zero-based multipart part index currently being uploaded. */
     private _currentPartIndex;
+    /** True when payload uses multipart flow. */
+    private _isMultipart;
+    /** Provider tier returned by control plane. */
+    private _tier?;
+    /** Active XMLHttpRequest handle for cancellation/pause semantics. */
     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. */
+    constructor(client: HttpClient, path: string, data: Blob, 
+    /** Filename */
+    name: string, contentType: string, options: UploadOptions, 
+    /** Tenant ID, inherited from SDK config */
+    tenantId: string);
+    /**
+     * Register observers for upload lifecycle events.
+     * @param event Only `'state_changed'` is supported.
+     * @param nextOrObserver Progress callback or observer object.
+     * @param error Error callback.
+     * @param complete Completion callback.
+     * @returns Unsubscribe function.
+     */
     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 the upload. Works natively for multipart; simple uploads will restart on resume. */
     pause(): boolean;
-    /** Resume a paused upload. */
+    /** Resume a paused upload from where it left off (multipart) or restart (simple). */
     resume(): boolean;
-    /** Permanently cancel the upload, cleaning up partial server state if necessary. */
+    /** Permanently cancel the upload, cleaning up any in-progress server state. */
     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>;
@@ -58,85 +107,271 @@ declare class UploadTask implements Promise<UploadResult> {
     finally(onfinally?: (() => void) | null): Promise<UploadResult>;
     readonly [Symbol.toStringTag] = "UploadTask";
     private _start;
+    /**
+     * Simple upload path (< 50 MB):
+     * 1. Obtain a presigned upload URL from the control plane
+    * 2. PUT directly to MinIO/S3 from the browser
+     * 3. Confirm via control plane (updates metadata, triggers quota + audit)
+     */
     private _startSimple;
-    private _startResumable;
-    private _continueResumable;
-    private _uploadChunkWithProgress;
+    /**
+     * Multipart upload path (>= 50 MB) via Tier 1 (S3):
+     * 1. Initiate multipart session on control plane
+     * 2. Upload each chunk to a separate presigned URL
+     * 3. Complete the session (S3 assembles the object)
+     */
+    private _startMultipart;
+    private _continueMultipart;
+    private _putToPresignedUrl;
+    private _uploadChunkXhr;
+    /** Pushes a fresh snapshot to all registered observers. */
     private _notifyObservers;
+    /** Centralized terminal error handler for all upload flows. */
     private _handleError;
 }
 
+/** SDK initialization config */
 interface TelestackConfig {
+    /** Full URL to your TelestackStorage worker, e.g. https://storage.example.com */
     baseUrl: string;
+    /** Tenant ID — scopes all operations to a specific tenant's bucket */
+    tenantId: string;
+    /** Optional project context used by internal/admin operations */
+    projectId?: string;
+    /** Optional organization context used by internal/admin operations */
+    orgId?: string;
+    /** API Key for server-to-server or developer access */
     apiKey?: string;
+    /** JWT Bearer token for end-user auth (from your auth provider) */
     token?: string;
-    tenantId: string;
+    /** Default upload options applied to all uploads */
     defaultUploadOptions?: Partial<UploadOptions>;
 }
+/** Represents a file stored in TelestackStorage */
 interface FileMetadata {
-    id: string;
+    /** Internal document ID */
+    $id: string;
+    /** Tenant/project id owning this file. */
     tenant_id: string;
-    path: string;
+    /** Parent directory id (`root` for root-level files). */
+    directory_id: string;
+    /** File display name. */
     name: string;
+    /** Canonical hashed path used for lookups. */
+    path_hash: string;
+    /** Current active version id. */
+    current_version_id: string;
+    /** Cached file size in bytes. */
+    cached_size: number;
+    /** Lifecycle status in metadata DB. */
+    status: 'pending' | 'active' | 'deleted';
+    /** ISO timestamp when metadata row was created. */
+    created_at: string;
+    /** ISO timestamp when metadata row was last updated. */
+    updated_at: string;
+}
+/** Represents a specific version of a stored file */
+interface FileVersionMetadata {
+    /** Version row id. */
+    $id: string;
+    /** Parent file id. */
+    file_id: string;
+    /** Object storage key for this specific version. */
+    storage_key: string;
+    /** 'tier1' = S3-compatible (MinIO/R2/S3) */
+    provider: 'tier1';
+    /** Version size in bytes. */
     size: number;
+    /** MIME type recorded for this version. */
     content_type: string;
+    /** Provider ETag if available. */
+    etag?: string;
+    /** ISO timestamp when the version row was created. */
+    created_at: string;
+}
+/** A bucket record corresponding to a tenant's storage configuration */
+interface BucketMetadata {
+    /** Bucket row id. */
+    $id: string;
+    /** Tenant/project id owning the bucket. */
+    tenant_id: string;
+    /** Organization/owner id associated with the bucket. */
     owner_id: string;
-    status: 'pending' | 'active' | 'deleted';
-    metadata: Record<string, any>;
+    /** Bucket-level public-read toggle. */
+    is_public: boolean;
+    /** Physical storage tier. */
+    tier: 'tier1';
+    /** Commercial plan for this bucket. */
+    plan: 'free' | 'paid';
+    /** Operational status for access control. */
+    status: 'active' | 'suspended';
+    /** Quota limit in bytes. */
+    storage_limit: number;
+    /** ISO timestamp when bucket row was created. */
     created_at: string;
+    /** ISO timestamp when bucket row was last updated. */
     updated_at: string;
 }
+/** Options for upload operations */
 interface UploadOptions {
-    tenantId?: string;
-    userId: string;
-    metadata?: Record<string, any>;
+    /** User ID to associate with the upload */
+    userId?: string;
+    /** Directory ID to place the file into (defaults to root) */
+    directoryId?: string;
+    /** Size of each multipart chunk in bytes (default: 10MB) */
     chunkSize?: number;
+    /** Base64 AES-GCM key for client-side E2EE before upload */
     encryptionKey?: string;
+    /** Image compression settings applied before upload */
     compressImage?: {
         maxWidth?: number;
         maxHeight?: number;
+        /** 0.0 (worst) to 1.0 (best), default 0.85 */
         quality?: number;
     };
 }
+/** Options for download operations */
 interface DownloadOptions {
+    /** Retrieve a specific version by its ID */
     versionId?: string;
+    /** Expiry in seconds for the presigned URL (default: 3600) */
+    expiresIn?: number;
+    /** Download mode for content disposition handling */
+    mode?: 'download' | 'inline';
 }
+/** Options for listing files */
 interface ListOptions {
-    prefix?: string;
+    /** Parent directory id, or `null` for root. */
+    directoryId?: string | null;
+    /** Max records to return. */
     limit?: number;
+    /** Pagination offset. */
+    offset?: number;
 }
+/** Options for searching files */
 interface SearchOptions {
+    /** Name prefix or substring filter */
     query?: string;
-    metadata?: Record<string, any>;
+    /** Filter by file extension, e.g. 'pdf' */
+    extension?: string;
+    /** Filter by minimum file size in bytes */
+    minSize?: number;
     limit?: number;
+    offset?: number;
 }
+/** Result of a search query */
 interface SearchResult {
+    /** True on successful query execution. */
     success: boolean;
+    /** Matched files after filtering. */
     files: FileMetadata[];
+    /** Total records returned by the current query. */
+    total: number;
 }
+/** Result of a completed upload */
 interface UploadResult {
-    file: FileMetadata;
+    /** True when upload/confirm flow completed successfully. */
+    success: boolean;
+    /** File metadata id. */
+    file_id: string;
+    /** Active version id. */
+    version_id: string;
+    /** Whether multipart S3 upload was used */
     resumable: boolean;
 }
+/** Result of a batch delete */
 interface BatchDeleteResult {
+    /** True when batch request is accepted/completed. */
     success: boolean;
-    deletedCount: number;
-    errors: any[];
+    /** Status message (queued or completed). */
+    message: string;
 }
-interface BatchCopyResult {
+/** Result of a batch copy/move */
+interface BatchMutationResult {
+    /** True when batch request succeeds. */
     success: boolean;
+    /** Provider result payloads per item. */
     results: any[];
 }
-interface TagSet {
-    Key: string;
-    Value: string;
+/** Public path visibility rule for selective anonymous access. */
+interface PublicPathRule {
+    /** Rule row id. */
+    $id: string;
+    /** Tenant/project id owning the rule. */
+    tenant_id: string;
+    /** Public prefix (no trailing wildcard in DB). */
+    path_prefix: string;
+    /** Public-read toggle for this prefix. */
+    is_public: boolean;
+    /** ISO timestamp when rule was created. */
+    created_at: string;
+}
+/** Response payload for API key generation. */
+interface GeneratedApiKeyResponse {
+    /** True when key creation succeeds. */
+    success: boolean;
+    /** Plaintext API key. Returned once and must be stored client-side securely. */
+    apiKey: string;
+    key: {
+        /** API key row id. */
+        id: string;
+        /** Display name assigned to the key. */
+        name: string;
+        /** Tenant/project id associated with the key. */
+        tenant_id: string;
+        /** ISO timestamp when the key was created. */
+        created_at: string;
+    };
+}
+/** Storage usage analytics for a tenant */
+interface TenantUsageStats {
+    /** Aggregated stored bytes. */
+    total_bytes: number;
+    /** Aggregated active file count. */
+    total_files: number;
+    /** ISO timestamp of last aggregation sync. */
+    last_aggregated_at: string;
 }
-/** Upload State Enum exactly like Firebase */
+/** Time-series analytics data point */
+interface UsageAnalytics {
+    /** Read operation count. */
+    reads: number;
+    /** Write operation count. */
+    writes: number;
+    /** Bandwidth usage in bytes. */
+    bandwidth: number;
+    /** Aggregation period in days. */
+    period_days: number;
+}
+/** A real-time event emitted from the SSE stream */
+interface StorageEvent {
+    /** Event row id. */
+    $id: string;
+    /** Tenant/project id for the event. */
+    tenant_id: string;
+    /** Event type key (e.g. `file.upload.confirmed`). */
+    event_type: string;
+    /** Logical resource type affected by the event. */
+    resource_type: string;
+    /** Resource id affected by the event. */
+    resource_id: string;
+    /** JSON payload string for event-specific context. */
+    payload: string;
+    /** Monotonic sequence for event stream ordering. */
+    sequence_number: string;
+    /** ISO timestamp when event was written. */
+    created_at: string;
+}
+/** Upload state, matching Firebase Storage semantics */
 type UploadState = 'processing' | 'running' | 'paused' | 'success' | 'error' | 'canceled';
 interface UploadTaskSnapshot {
+    /** Uploaded bytes at this observation point. */
     bytesTransferred: number;
+    /** Total bytes for this upload task. */
     totalBytes: number;
+    /** Current upload lifecycle state. */
     state: UploadState;
+    /** Reference to the associated UploadTask instance. */
     task: UploadTask;
 }
 type Observer<T> = {
@@ -146,156 +381,402 @@ type Observer<T> = {
 };
 
 /**
- * Base abstract reference to a location in Telestack Storage.
+ * Base class for Telestack path references.
  */
 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. */
+    /**
+     * Navigate to a child path. Returns a FileRef or DirRef based on whether
+     * the resulting path ends with a `/`.
+     */
     child(childPath: string): StorageRef;
 }
 /**
- * Reference exclusively to a Directory (Prefix).
+ * Reference to a directory (folder) in Telestack Storage.
  */
 declare class DirRef extends StorageRef {
-    /** Retrieve all files immediately within this directory prefix. */
-    listAll(limit?: number): Promise<FileMetadata[]>;
+    /**
+     * List all files in this directory.
+     */
+    listAll(options?: ListOptions): Promise<{
+        files: FileMetadata[];
+        directories: any[];
+    }>;
+    /**
+     * Create this directory and get back the directory document.
+     */
+    create(parentId?: string): Promise<any>;
+    /**
+     * Delete this directory and all its contents asynchronously (background queue).
+     */
+    delete(directoryId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Search within this directory's prefix.
+     */
+    search(options: SearchOptions): Promise<SearchResult>;
 }
 /**
- * Reference exclusively to a File object.
+ * Reference to a specific file in Telestack Storage.
+ *
+ * @example
+ * ```ts
+ * const fileRef = storage.ref('documents/report.pdf');
+ *
+ * // Upload with progress tracking
+ * const task = fileRef.put(pdfBlob, { userId: 'u_abc' });
+ * task.on('state_changed', snap => console.log(snap.bytesTransferred));
+ *
+ * // Download URL
+ * const url = await fileRef.getDownloadUrl();
+ * ```
  */
 declare class FileRef extends StorageRef {
+    private resolveFileRecord;
     /**
-     * Upload a File/Blob, returning an UploadTask that can be observed, paused, and cancelled.
-     * Functions identically to Firebase Storage.
+     * Upload a File or Blob. Returns an UploadTask you can observe, pause,
+     * resume, and cancel — just like Firebase Storage.
      */
-    put(data: File | Blob, options: UploadOptions): UploadTask;
+    put(data: File | Blob, options?: UploadOptions): UploadTask;
     /**
-     * Upload raw bytes directly.
+     * Upload raw bytes.
      */
-    putBytes(data: ArrayBuffer, contentType: string, options: UploadOptions): UploadTask;
-    /** Get a time-limited presigned download URL. */
-    getDownloadUrl(options?: DownloadOptions): Promise<string>;
+    putBytes(data: ArrayBuffer, contentType: string, options?: UploadOptions): UploadTask;
     /**
-     * Securely downloads and decrypts an E2EE file entirely within the browser.
-     * Requires the exact Base64 AES-GCM key used during `put()`.
+     * Get a time-limited presigned download URL (302 redirect to CDN/S3).
      */
-    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>;
+    getDownloadUrl(fileId?: string, options?: DownloadOptions): Promise<string>;
+    /**
+     * Access this file via the public CDN URL (only works if bucket is_public = true).
+     * Returns the redirect URL directly.
+     */
+    getCdnUrl(path: string): string;
+    /**
+     * Download and decrypt an E2EE-encrypted file entirely in the browser.
+     * Requires the same Base64 AES-GCM key used during upload.
+     */
+    getDecryptedBlob(encryptionKey: string, originalMimeType: string, fileId?: string): Promise<Blob>;
+    /**
+     * Get the file's metadata record from the database.
+     */
+    getMetadata(fileId?: string): Promise<FileMetadata>;
+    /**
+     * Get all versions of this file.
+     */
+    getVersions(fileId?: string): Promise<FileVersionMetadata[]>;
+    /**
+     * Soft-delete a file (marks as deleted, preserves versions).
+     */
+    delete(fileId?: string): Promise<void>;
 }
 
 /**
  * Fluent builder for batch file operations.
- * Operations execute identically as single network requests over the backend API.
+ * Each operation compiles to a single API request, handled by the background queue
+ * for large datasets to keep the API responsive.
  *
  * @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();
+ * ```ts
+ * // Delete multiple files
+ * await storage.batch().delete(['fileId1', 'fileId2']).run();
+ *
+ * // Copy files to a new directory
+ * await storage.batch().copy([{ sourceId: 'id1', destDirId: 'dir2', destName: 'copy.pdf', destPath: 'docs/copy.pdf' }]).run();
+ * ```
  */
 declare class BatchBuilder {
     private readonly client;
+    private readonly tenantId;
     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>;
+    private _fileIds;
+    private _mappings;
+    constructor(client: HttpClient, tenantId: string);
+    /**
+     * Queue file IDs for batch deletion. Runs in background queue.
+     */
+    delete(fileIds: string[]): this;
+    /**
+     * Queue copy operations (file ID → new directory).
+     */
+    copy(mappings: {
+        sourceId: string;
+        destDirId: string;
+        destName: string;
+        destPath: string;
+    }[]): this;
+    /**
+     * Queue move operations (file ID → new directory/name).
+     */
+    move(mappings: {
+        fileId: string;
+        destDirId: string;
+        destName: string;
+        destPath: string;
+    }[]): this;
+    /**
+     * Execute the queued batch operation.
+     */
+    run(): Promise<BatchDeleteResult | BatchMutationResult>;
 }
 
 /**
  * Fluent builder for searching files via Metadata or Full-Text queries.
  *
  * @example
+ * ```ts
  * const files = await storage.query()
- *   .where('project', 'Q1')
- *   .nameContains('report')
+ *   .search('report')
+ *   .withExtension('pdf')
+ *   .minSize(1024)
  *   .limit(10)
  *   .get();
+ * ```
  */
 declare class QueryBuilder {
     private readonly client;
+    private readonly tenantId;
     private _query;
-    private _metadata;
+    private _extension;
+    private _minSize;
     private _limit;
-    constructor(client: HttpClient);
-    nameContains(text: string): this;
-    where(key: string, value: any): this;
+    private _offset;
+    constructor(client: HttpClient, tenantId: string);
+    /** Find files whose names match this text */
+    search(text: string): this;
+    /** Filter by file extension (e.g., 'pdf', 'png') */
+    withExtension(ext: string): this;
+    /** Filter by minimum file size in bytes */
+    minSize(bytes: number): this;
+    /** Set the maximum number of results (default 20, max 100) */
     limit(n: number): this;
+    /** Set the number of results to skip (for pagination) */
+    offset(n: number): this;
+    /** Execute the search and return the list of matching files */
     get(): Promise<FileMetadata[]>;
+    /** Alias for get() */
+    run(): Promise<FileMetadata[]>;
 }
 
 /**
- * TelestackStorage — The main SDK client.
- * More comprehensive and fluent than Firebase/Appwrite Storage.
+ * @class TelestackStorage
+ * The main entry point for the Telestack Storage Web SDK.
+ *
+ * Mirrors Firebase Storage's fluent `.ref()` API while adding enterprise-grade
+ * features: tiered storage (Internal + S3), realtime SSE, analytics, search,
+ * and batch operations.
  *
  * @example
  * ```ts
+ * import { TelestackStorage } from '@telestack/storage-web';
+ *
  * const storage = new TelestackStorage({
  *   baseUrl: 'https://storage.yourdomain.com',
- *   tenantId: 'your_tenant_id',
- *   apiKey: 'tk_your_api_key',
+ *   tenantId: 'tenant_abc',
+ *   apiKey: 'tk_live_xxx',
  * });
  *
- * // 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!')
- * );
+ * // Upload a file
+ * const task = storage.ref('photos/avatar.png').put(file);
+ * task.on('state_changed', snap => {
+ *   const pct = (snap.bytesTransferred / snap.totalBytes * 100).toFixed(0);
+ *   console.log(`${pct}% uploaded`);
+ * }, console.error, () => console.log('Done!'));
  *
- * // Later...
- * task.pause();
- * task.resume();
+ * // Search files
+ * const results = await storage.search({ query: 'report', extension: 'pdf' });
+ *
+ * // Usage analytics
+ * const stats = await storage.getUsageStats(7);
  * ```
  */
 declare class TelestackStorage {
     private readonly config;
-    private readonly http;
+    /** @internal */
+    readonly http: HttpClient;
     readonly tenantId: string;
     constructor(config: TelestackConfig);
-    /** Get a highly-fluent reference to a specific file. */
+    /**
+     * Create a cloned client with updated tenant/project/org defaults.
+     * Helpful in multi-tenant consoles where context changes often.
+     */
+    withContext(context: {
+        tenantId?: string;
+        projectId?: string;
+        orgId?: string;
+    }): TelestackStorage;
+    /**
+     * Create a cloned client with updated auth credentials.
+     * Passing `null` explicitly clears an existing credential.
+     */
+    withAuth(auth: {
+        apiKey?: string | null;
+        token?: string | null;
+    }): TelestackStorage;
+    /**
+     * Get a fluent reference to a specific file path.
+     * Use this as the starting point for uploads, downloads, and file metadata.
+     *
+     * @param path - Full path within the tenant bucket, e.g. `'documents/report.pdf'`
+     */
     ref(path: string): FileRef;
-    /** Get a highly-fluent reference to a directory/prefix. */
+    /**
+     * Get a fluent reference to a directory (prefix).
+     *
+     * @param path - Directory path, e.g. `'documents/'` or `'images'`
+     */
     dir(path: string): DirRef;
-    /** Helper: List files for the entire bucket/tenant or specific prefix. */
-    list(options?: ListOptions): Promise<FileMetadata[]>;
-    /** Rename a single file or directory prefix. */
-    rename(oldPath: string, newName: string): Promise<{
-        success: boolean;
-        newPath: string;
+    /**
+     * Get this tenant's bucket configuration.
+     */
+    getBucket(): Promise<BucketMetadata>;
+    /**
+     * List files in a directory. Pass `null` for the root.
+     */
+    list(options?: ListOptions): Promise<{
+        files: FileMetadata[];
+        directories: any[];
     }>;
-    /** 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. */
+    /**
+     * Search files by name, extension, or minimum size.
+     *
+     * @example
+     * ```ts
+     * const { files, total } = await storage.search({ query: 'invoice', extension: 'pdf' });
+     * ```
+     */
+    search(options: SearchOptions): Promise<SearchResult>;
+    /**
+     * Get a fluent query builder for advanced searching.
+     *
+     * @example
+     * ```ts
+     * const files = await storage.query().search('invoice').get();
+     * ```
+     */
     query(): QueryBuilder;
-    /** Generate a new API key (admin only). The key is shown only once. */
-    generateApiKey(name?: string): Promise<{
-        apiKey: string;
+    /**
+     * Get a fluent batch operation builder.
+     *
+     * @example
+     * ```ts
+     * await storage.batch()
+     *   .delete(['id1', 'id2', 'id3'])
+     *   .commit();
+     * ```
+     */
+    batch(): BatchBuilder;
+    /**
+     * Bulk delete files by their IDs. Queued in background for large lists.
+     */
+    batchDelete(fileIds: string[]): Promise<BatchDeleteResult>;
+    /**
+     * Copy multiple files to new directories simultaneously.
+     */
+    batchCopy(mappings: {
+        sourceId: string;
+        destDirId: string;
+        destName: string;
+        destPath: string;
+    }[]): Promise<BatchMutationResult>;
+    /**
+     * Move multiple files to new directories/names simultaneously.
+     */
+    batchMove(mappings: {
+        fileId: string;
+        destDirId: string;
+        destName: string;
+        destPath: string;
+    }[]): Promise<BatchMutationResult>;
+    /**
+     * Get aggregated storage usage for the tenant.
+     *
+     * @param days - Number of days to include in the time window (default: 7)
+     */
+    getUsageStats(days?: number): Promise<UsageAnalytics>;
+    /**
+     * Subscribe to real-time storage events for this tenant via SSE.
+     * Events include file uploads, deletions, and system changes.
+     *
+     * @returns An `unsubscribe` function — call it to close the connection.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = storage.onEvent((event) => {
+     *   console.log(event.event_type, event.resource_id);
+     * });
+     *
+     * // Later
+     * unsubscribe();
+     * ```
+     */
+    onEvent(callback: (event: StorageEvent) => void): () => void;
+    /**
+     * Initialize the internal database schema (admin only — run once on bootstrap).
+     */
+    initDatabase(): Promise<{
+        success: boolean;
         message: string;
     }>;
-    /** Revoke an API key by its ID. */
+    /**
+     * Generate a new API key (admin only). The raw key is returned once — store it securely.
+     *
+     * @example
+     * ```ts
+     * const { apiKey } = await storage.generateApiKey('my-backend-service');
+     * ```
+     */
+    generateApiKey(name?: string): Promise<GeneratedApiKeyResponse>;
+    /**
+     * Revoke an existing API key by its database ID.
+     */
     revokeApiKey(keyId: string): Promise<void>;
-    /** Get S3 bucket configuration details. */
-    getBucketInfo(): Promise<any>;
+    /**
+     * Read analytics from internal admin API for the configured tenant.
+     */
+    getInternalAnalytics(tenantId?: string): Promise<Array<{
+        date: string;
+        reads: number;
+        writes: number;
+        bandwidth: number;
+    }>>;
+    /**
+     * Fetch internal bucket information including effective quota.
+     */
+    getInternalBucketInfo(tenantId?: string): Promise<{
+        tier: string;
+        quotaLimit: number;
+        bucket: BucketMetadata;
+    }>;
+    /**
+     * Toggle bucket visibility from internal admin API.
+     */
+    updateBucketVisibility(isPublic: boolean, tenantId?: string): Promise<{
+        success: boolean;
+        bucket: BucketMetadata;
+    }>;
+    /**
+     * List granular public path rules.
+     */
+    listPublicPathRules(tenantId?: string): Promise<PublicPathRule[]>;
+    /**
+     * Add a granular public path rule.
+     */
+    addPublicPathRule(pathPrefix: string, tenantId?: string): Promise<PublicPathRule>;
+    /**
+     * Delete a granular public path rule by id.
+     */
+    deletePublicPathRule(ruleId: string, tenantId?: string): Promise<void>;
+}
+
+declare class TelestackError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
 }
 
 declare class CryptoHelper {
@@ -331,4 +812,4 @@ declare class ImageHelper {
     }): 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 };
+export { BatchBuilder, type BatchDeleteResult, type BatchMutationResult, type BucketMetadata, CryptoHelper, DirRef, type DownloadOptions, type FileMetadata, FileRef, type FileVersionMetadata, type GeneratedApiKeyResponse, HttpClient, ImageHelper, type ListOptions, type Observer, type PublicPathRule, QueryBuilder, type SearchOptions, type SearchResult, type StorageEvent, StorageRef, type TelestackConfig, TelestackError, TelestackStorage, type TenantUsageStats, type UploadOptions, type UploadResult, type UploadState, UploadTask, type UploadTaskSnapshot, type UsageAnalytics };