hydrousdb 2.0.1 → 2.0.3

package/dist/index.d.mts

@@ -1,9 +1,30 @@
+/**
+ * Named storage keys.
+ * Create as many as you need in the HydrousDB dashboard and give each one a
+ * meaningful name — you'll reference it by name when calling storage methods.
+ *
+ * @example
+ * {
+ *   main:      'ssk_main_…',
+ *   avatars:   'ssk_avatars_…',
+ *   documents: 'ssk_docs_…',
+ * }
+ */
+type StorageKeys = Record<string, string>;
 interface HydrousConfig {
-    /** Your Hydrous project URL  e.g. https://api.yourapp.hydrous.app */
+    /** Your HydrousDB project base URL */
     url: string;
-    /** Your project API key */
-    apiKey: string;
-    /** Optional default request timeout in milliseconds (default: 30_000) */
+    /** Auth service key — used for all auth.* operations */
+    authKey: string;
+    /** Bucket security key — used for records.* and analytics.* operations */
+    bucketSecurityKey: string;
+    /**
+     * Storage keys object.  Each property name is a label you choose; each
+     * value is a storage key (ssk_…) from your dashboard.
+     * You can have as many as you need.
+     */
+    storageKeys: StorageKeys;
+    /** Optional global request timeout in milliseconds (default: 30 000) */
     timeout?: number;
 }
 interface HydrousResponse<T = unknown> {
@@ -84,37 +105,28 @@ interface AnalyticsEvent {
     sessionId?: string;
     timestamp: number;
 }
-/** The bucket key (ssk_…) that authorizes access to a specific storage bucket */
-type BucketKey = string;
 type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
-/** Fired for every progress tick during an upload */
 interface UploadProgress {
-    /** 0-based index (always 0 for single uploads) */
+    /** 0-based file index (always 0 for single uploads) */
     index: number;
-    /** Total files in this operation */
+    /** Total files in the operation */
     total: number;
-    /** Destination path (relative to your bucket root) */
+    /** Destination path in the bucket */
     path: string;
     /** Current lifecycle stage */
     stage: UploadStage;
-    /** Bytes sent to the server so far */
     bytesUploaded: number;
-    /** Total bytes to send */
     totalBytes: number;
-    /** 0–100 integer */
+    /** 0 – 100 */
     percent: number;
-    /** Upload speed in bytes/second – null before the first tick */
+    /** Upload speed in bytes/sec; null until the first tick */
     bytesPerSecond: number | null;
-    /** Estimated seconds remaining – null until speed is known */
+    /** Estimated seconds remaining; null until speed is known */
     eta: number | null;
-    /** Set when stage === 'done' */
     result?: UploadResult;
-    /** Set when stage === 'error' */
     error?: string;
-    /** Set when stage === 'error' */
     code?: string;
 }
-/** Per-file progress during a batch download */
 interface DownloadProgress {
     index: number;
     total: number;
@@ -199,67 +211,44 @@ interface StorageStats {
     compressionRatio: string;
 }
 interface UploadOptions {
-    /**
-     * Destination path within your bucket (e.g. "avatars/photo.jpg").
-     * Defaults to the file's original name.
-     */
+    /** Destination path in the bucket (defaults to the file's original name) */
     path?: string;
-    /**
-     * Replace the file if it already exists at the given path.
-     * @default false
-     */
+    /** Replace the file if it already exists (default: false) */
     overwrite?: boolean;
     /**
-     * Called on every progress tick while the file is being transferred.
-     * Use this to drive progress bars, speed indicators, and ETAs.
+     * Called on every progress tick.
+     * Use this to drive progress bars, speed displays, and ETAs.
      */
     onProgress?: (progress: UploadProgress) => void;
 }
 interface BatchUploadOptions {
-    /**
-     * Folder prefix to prepend to all file names (e.g. "uploads/2024/").
-     * Individual path overrides take precedence if provided.
-     */
+    /** Folder prefix prepended to every filename */
     prefix?: string;
-    /**
-     * Per-file destination paths in the same order as the `files` array.
-     * If omitted, `prefix + file.name` is used.
-     */
+    /** Per-file paths (same order as the `files` array; takes priority over prefix) */
     paths?: string[];
-    /** @default false */
     overwrite?: boolean;
-    /** Max simultaneous uploads (1–10). @default 5 */
+    /** Max simultaneous server-side uploads (1–10, default 5) */
     concurrency?: number;
-    /**
-     * Called on every progress tick for every file.
-     * The `index` field identifies which file the event belongs to.
-     */
+    /** Called for every progress tick on every file */
     onProgress?: (progress: UploadProgress) => void;
 }
 interface BatchDownloadOptions {
-    /** Max simultaneous downloads (1–10). @default 5 */
     concurrency?: number;
-    /**
-     * Called when each file's download status changes.
-     */
     onProgress?: (progress: DownloadProgress) => void;
     /**
-     * When true, automatically triggers browser download for each file as
-     * it arrives. Only works in browser environments.
-     * @default false
+     * Browser only — automatically triggers a Save dialog for each file as it
+     * arrives (default: false)
      */
     autoSave?: boolean;
 }
 interface ListOptions {
-    /** Folder prefix to list (e.g. "avatars/"). Empty string = root. */
+    /** Folder prefix to list (empty = bucket root) */
     prefix?: string;
-    /** Max items per page (1–100). @default 50 */
     limit?: number;
-    /** Pagination cursor returned from the previous call. */
     cursor?: string;
 }
 interface SignedUrlOptions {
-    /** How long the URL stays valid, in seconds. @default 3600 (1 hour) */
+    /** How long the URL stays valid in seconds (default: 3600) */
     expiresIn?: number;
 }
 
@@ -268,39 +257,17 @@ declare class AuthClient {
     private readonly headers;
     private session;
     constructor(config: HydrousConfig);
-    /**
-     * Create a new user account and return a session.
-     *
-     * @example
-     * const { data, error } = await hydrous.auth.signUp({
-     *   email:    'user@example.com',
-     *   password: 'supersecret',
-     * });
-     */
+    /** Create a new user account */
     signUp(options: SignUpOptions): Promise<HydrousResponse<AuthSession>>;
-    /**
-     * Sign in with email and password.
-     *
-     * @example
-     * const { data, error } = await hydrous.auth.signIn({
-     *   email:    'user@example.com',
-     *   password: 'supersecret',
-     * });
-     * if (data) console.log('Signed in as', data.user.email);
-     */
+    /** Sign in with email and password */
     signIn(options: SignInOptions): Promise<HydrousResponse<AuthSession>>;
-    /**
-     * Sign out the current user and invalidate their session.
-     */
+    /** Sign out and invalidate the current session */
     signOut(): Promise<HydrousResponse<void>>;
-    /** Return the currently authenticated user, or null if not signed in. */
+    /** Get the currently authenticated user */
     getUser(): Promise<HydrousResponse<AuthUser>>;
-    /**
-     * Refresh the access token using the stored refresh token.
-     * Called automatically by the SDK when a 401 is received.
-     */
+    /** Refresh the access token using the stored refresh token */
     refreshSession(): Promise<HydrousResponse<AuthSession>>;
-    /** Return the current in-memory session (may be null). */
+    /** Return the current in-memory session (may be null) */
     getSession(): AuthSession | null;
     private _sessionHeader;
 }
@@ -309,60 +276,15 @@ declare class RecordsClient {
     private readonly baseUrl;
     private readonly headers;
     constructor(config: HydrousConfig);
-    /**
-     * Query records from a collection.
-     *
-     * @param collection - Collection name (e.g. "users")
-     * @param options    - Filters, ordering, pagination
-     *
-     * @example
-     * const { data, error } = await hydrous.records.select('users', {
-     *   where:   { field: 'role', operator: 'eq', value: 'admin' },
-     *   orderBy: { field: 'createdAt', direction: 'desc' },
-     *   limit:   20,
-     * });
-     */
+    /** Query records from a collection */
     select<T = Record<string, unknown>>(collection: string, options?: QueryOptions): Promise<RecordResponse<T>>;
-    /**
-     * Fetch a single record by its ID.
-     *
-     * @example
-     * const { data, error } = await hydrous.records.get('users', 'user_abc123');
-     */
+    /** Fetch a single record by ID */
     get<T = Record<string, unknown>>(collection: string, id: string): Promise<SingleRecordResponse<T>>;
-    /**
-     * Insert one or more records into a collection.
-     *
-     * @param collection - Collection name
-     * @param payload    - A single record object or an array of record objects
-     *
-     * @example
-     * // Single insert
-     * const { data, error } = await hydrous.records.insert('users', {
-     *   name: 'Alice', email: 'alice@example.com'
-     * });
-     *
-     * // Bulk insert
-     * const { data, error } = await hydrous.records.insert('users', [
-     *   { name: 'Alice' }, { name: 'Bob' }
-     * ]);
-     */
+    /** Insert one or more records */
     insert<T = Record<string, unknown>>(collection: string, payload: Partial<T> | Partial<T>[]): Promise<RecordResponse<T>>;
-    /**
-     * Update a record by ID.
-     *
-     * @example
-     * const { data, error } = await hydrous.records.update('users', 'user_abc123', {
-     *   name: 'Alice Smith'
-     * });
-     */
+    /** Update a record by ID */
     update<T = Record<string, unknown>>(collection: string, id: string, payload: Partial<T>): Promise<SingleRecordResponse<T>>;
-    /**
-     * Delete a record by ID.
-     *
-     * @example
-     * const { error } = await hydrous.records.delete('users', 'user_abc123');
-     */
+    /** Delete a record by ID */
     delete(collection: string, id: string): Promise<SingleRecordResponse<void>>;
 }
 
@@ -370,97 +292,63 @@ declare class AnalyticsClient {
     private readonly baseUrl;
     private readonly headers;
     constructor(config: HydrousConfig);
-    /**
-     * Track an analytics event.
-     *
-     * @example
-     * await hydrous.analytics.track({
-     *   event:      'page_view',
-     *   properties: { page: '/home', referrer: 'google.com' },
-     *   userId:     'user_abc123',
-     * });
-     */
+    /** Track a single analytics event */
     track(options: TrackEventOptions): Promise<HydrousResponse<void>>;
-    /**
-     * Query recorded analytics events.
-     *
-     * @example
-     * const { data } = await hydrous.analytics.query({
-     *   event: 'page_view',
-     *   from:  '2024-01-01',
-     *   to:    '2024-01-31',
-     *   limit: 100,
-     * });
-     */
-    query(options?: AnalyticsQueryOptions): Promise<RecordResponse<AnalyticsEvent>>;
-    /**
-     * Track multiple events in a single request (more efficient than
-     * calling `track` in a loop).
-     *
-     * @example
-     * await hydrous.analytics.trackBatch([
-     *   { event: 'signup',   userId: 'u1' },
-     *   { event: 'onboarded', userId: 'u1' },
-     * ]);
-     */
+    /** Track many events in one request */
     trackBatch(events: TrackEventOptions[]): Promise<HydrousResponse<void>>;
+    /** Query recorded analytics events */
+    query(options?: AnalyticsQueryOptions): Promise<RecordResponse<AnalyticsEvent>>;
 }
 
-declare class StorageClient {
-    private readonly baseUrl;
-    constructor(config: HydrousConfig);
+/**
+ * A storage client that is already bound to a specific storage key.
+ * You get one of these by calling  `db.storage('keyName')`.
+ *
+ * None of the methods on this class require you to pass a bucket key —
+ * it's already baked in.
+ */
+declare class ScopedStorageClient {
+    private readonly base;
+    private readonly key;
+    readonly keyName: string;
+    constructor(baseUrl: string, keyName: string, bucketKey: string);
     /**
-     * Upload a single file to a bucket.
+     * Upload a single file.
      *
-     * The bucket key **always comes first**.
-     * Supply an `onProgress` callback to receive live upload progress including
-     * bytes transferred, speed (bytes/sec), ETA, and lifecycle stage.
+     * Supply `onProgress` to receive live upload ticks including bytes
+     * transferred, speed (bytes/sec), ETA, and lifecycle stage.
      *
-     * ### Stages fired via `onProgress`
-     * | Stage        | Meaning                                 |
-     * |-------------|------------------------------------------|
-     * | `pending`   | Queued, not yet started                 |
-     * | `compressing` | Server is compressing the file         |
-     * | `uploading` | Bytes flowing to cloud storage           |
-     * | `done`      | Confirmed written to cloud storage       |
-     * | `error`     | Something went wrong                    |
+     * **Stage sequence:**
+     * `pending → compressing → uploading → done | error`
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param file       A `File`, `Blob`, or `Buffer` (Node)
-     * @param options    Path, overwrite flag, progress callback
+     * In browsers the progress is tracked at the network level via XHR, so
+     * `percent` reflects actual bytes leaving the device.  `done` only fires
+     * after the server confirms the write to cloud storage, so 100% is real.
      *
      * @example
-     * const { data, error } = await hydrous.storage.upload(
-     *   'ssk_my_bucket_key',
-     *   file,
-     *   {
-     *     path:       'avatars/alice.jpg',
-     *     overwrite:  true,
-     *     onProgress: (p) => {
-     *       console.log(`${p.stage} — ${p.percent}%  ${p.bytesPerSecond} B/s  ETA ${p.eta}s`);
-     *     },
-     *   }
-     * );
+     * const { data, error } = await db.storage('avatars').upload(file, {
+     *   path:      'users/alice.jpg',
+     *   overwrite: true,
+     *   onProgress: (p) => {
+     *     setProgress(p.percent);              // e.g. drive a <progress> bar
+     *     setSpeed(`${p.bytesPerSecond} B/s`);
+     *     setEta(`${p.eta}s remaining`);
+     *   },
+     * });
      */
-    upload(bucketKey: BucketKey, file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    upload(file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
     /**
-     * Upload raw text or JSON content directly — no `File` object needed.
-     * Great for saving generated content, config files, or JSON records.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param path       Destination path (e.g. `"configs/settings.json"`)
-     * @param content    String content to store
-     * @param options    `mimeType`, `overwrite`, `onProgress`
+     * Upload raw text or JSON content directly — no File object needed.
      *
      * @example
-     * await hydrous.storage.uploadText(
-     *   'ssk_my_bucket_key',
-     *   'reports/summary.txt',
-     *   'Hello from Hydrous!',
-     *   { mimeType: 'text/plain' }
+     * // Save a JSON config
+     * await db.storage('configs').uploadText(
+     *   'settings/app.json',
+     *   JSON.stringify({ theme: 'dark' }),
+     *   { mimeType: 'application/json' }
      * );
      */
-    uploadText(bucketKey: BucketKey, path: string, content: string, options?: {
+    uploadText(path: string, content: string, options?: {
         mimeType?: string;
         overwrite?: boolean;
         onProgress?: UploadOptions['onProgress'];
@@ -468,244 +356,199 @@ declare class StorageClient {
     /**
      * Upload multiple files in one request.
      *
-     * `onProgress` fires for **every file individually** — the `index` field
-     * tells you which file the event belongs to (0-based, same order as `files`).
-     * All files receive a `pending` event upfront before any uploads start,
-     * so you can render all progress bars immediately.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param files      Array of `File` objects (browser) or `{ name, data }` objects (Node)
-     * @param options    Prefix, per-file paths, overwrite, concurrency, onProgress
+     * `onProgress` fires per file — use `p.index` to identify which file.
+     * All files receive a `pending` event upfront so you can render progress
+     * bars immediately before any data is sent.
      *
      * @example
-     * await hydrous.storage.batchUpload(
-     *   'ssk_my_bucket_key',
-     *   fileArray,
-     *   {
-     *     prefix:     'uploads/2024/',
-     *     onProgress: (p) => {
-     *       console.log(`File ${p.index}: ${p.stage} ${p.percent}%`);
-     *     },
-     *   }
-     * );
+     * await db.storage('documents').batchUpload(files, {
+     *   prefix:     'reports/2024/',
+     *   onProgress: (p) => updateBar(p.index, p.percent),
+     * });
      */
-    batchUpload(bucketKey: BucketKey, files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    batchUpload(files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
     /**
      * Download a single file and return its content as an `ArrayBuffer`.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file within your bucket
-     *
      * @example
-     * const { data, error } = await hydrous.storage.download(
-     *   'ssk_my_bucket_key',
-     *   'avatars/alice.jpg'
-     * );
-     * if (data) {
-     *   const blob = new Blob([data]);
-     *   const url  = URL.createObjectURL(blob);
-     * }
+     * const { data } = await db.storage('avatars').download('users/alice.jpg');
+     * const blob = new Blob([data!]);
+     * img.src = URL.createObjectURL(blob);
      */
-    download(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    download(filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
     /**
      * Download multiple files in one request.
      *
-     * When `autoSave: true` (browser only) each file is automatically saved
-     * to the user's Downloads folder as it arrives.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePaths  Array of file paths within your bucket
-     * @param options    Concurrency, onProgress, autoSave
+     * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
      *
      * @example
-     * const { data } = await hydrous.storage.batchDownload(
-     *   'ssk_my_bucket_key',
-     *   ['reports/jan.pdf', 'reports/feb.pdf'],
-     *   {
-     *     onProgress: (p) => console.log(p.path, p.status),
-     *     autoSave:   true,  // triggers browser file-save dialog per file
-     *   }
+     * const { data } = await db.storage('reports').batchDownload(
+     *   ['jan.pdf', 'feb.pdf'],
+     *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
      * );
      */
-    batchDownload(bucketKey: BucketKey, filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    batchDownload(filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
     /**
-     * List files and folders inside a bucket (or a folder within it).
-     *
-     * Results are paginated — use `pagination.nextCursor` to fetch the next page.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param options    `prefix`, `limit`, `cursor`
+     * List files and folders (paginated).
      *
      * @example
-     * const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
-     *   prefix: 'avatars/',
-     *   limit:  50,
-     * });
-     * for (const item of data.items) {
-     *   console.log(item.type, item.path);
+     * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
+     * for (const item of data!.items) {
+     *   console.log(item.type, item.path, item.size);
      * }
      */
-    list(bucketKey: BucketKey, options?: ListOptions): Promise<HydrousResponse<ListResult>>;
-    /**
-     * Get metadata for a specific file (size, MIME type, compression info, etc.)
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file within your bucket
-     *
-     * @example
-     * const { data } = await hydrous.storage.metadata(
-     *   'ssk_my_bucket_key',
-     *   'avatars/alice.jpg'
-     * );
-     * console.log(data.size, data.mimeType);
-     */
-    metadata(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<FileMetadata>>;
-    /**
-     * Delete a single file.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file to delete
-     *
-     * @example
-     * await hydrous.storage.deleteFile('ssk_my_bucket_key', 'avatars/old.jpg');
-     */
-    deleteFile(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<void>>;
-    /**
-     * Recursively delete a folder and all of its contents.
-     *
-     * @param bucketKey   Your storage bucket key (`ssk_…`)
-     * @param folderPath  Folder path to delete (e.g. `"old-uploads/"`)
-     *
-     * @example
-     * await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
-     */
-    deleteFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
-    /**
-     * Create an empty folder.
-     *
-     * @param bucketKey   Your storage bucket key (`ssk_…`)
-     * @param folderPath  Path for the new folder (e.g. `"avatars/2024/"`)
-     *
-     * @example
-     * await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
-     */
-    createFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
-    /**
-     * Move (rename) a file to a new path.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param fromPath   Current path of the file
-     * @param toPath     New path for the file
-     *
-     * @example
-     * await hydrous.storage.move(
-     *   'ssk_my_bucket_key',
-     *   'drafts/report.pdf',
-     *   'published/report.pdf'
-     * );
-     */
-    move(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    list(options?: ListOptions): Promise<HydrousResponse<ListResult>>;
     /**
-     * Copy a file to a new path (original is kept).
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param fromPath   Source path
-     * @param toPath     Destination path
+     * Get metadata for a file (size, MIME type, compression, etc.)
      *
      * @example
-     * await hydrous.storage.copy(
-     *   'ssk_my_bucket_key',
-     *   'templates/invoice.pdf',
-     *   'invoices/invoice-001.pdf'
-     * );
-     */
-    copy(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+     * const { data: meta } = await db.storage('docs').metadata('report.pdf');
+     * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
+     */
+    metadata(filePath: string): Promise<HydrousResponse<FileMetadata>>;
+    /** Delete a single file */
+    deleteFile(filePath: string): Promise<HydrousResponse<void>>;
+    /** Recursively delete a folder and all its contents */
+    deleteFolder(folderPath: string): Promise<HydrousResponse<void>>;
+    /** Create an empty folder */
+    createFolder(folderPath: string): Promise<HydrousResponse<void>>;
+    /** Move (rename) a file */
+    move(fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    /** Copy a file (original is kept) */
+    copy(fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
     /**
      * Generate a time-limited public URL for a private file.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file
-     * @param options    `expiresIn` seconds (default: 3600)
-     *
      * @example
-     * const { data } = await hydrous.storage.signedUrl(
-     *   'ssk_my_bucket_key',
-     *   'private/contract.pdf',
-     *   { expiresIn: 300 }   // 5 minutes
-     * );
-     * console.log(data.signedUrl);  // share this URL
+     * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
+     * console.log(data!.signedUrl); // share this
      */
-    signedUrl(bucketKey: BucketKey, filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    signedUrl(filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
     /**
-     * Get usage and billing statistics for this bucket key.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * Get usage and billing stats for this storage key.
      *
      * @example
-     * const { data } = await hydrous.storage.stats('ssk_my_bucket_key');
-     * console.log(`${data.totalFiles} files, ${data.totalSizeBytes} bytes stored`);
+     * const { data } = await db.storage('main').stats();
+     * console.log(data!.totalFiles, data!.totalSizeBytes);
      */
-    stats(bucketKey: BucketKey): Promise<HydrousResponse<StorageStats>>;
+    stats(): Promise<HydrousResponse<StorageStats>>;
 }
 
+interface CallableStorage {
+    /** Get a scoped storage client by key name */
+    (keyName: string): ScopedStorageClient;
+    /** Same as calling db.storage(keyName) — more explicit */
+    use(keyName: string): ScopedStorageClient;
+    /** Return names of all configured storage keys */
+    keyNames(): string[];
+}
 /**
- * The root Hydrous client.
+ * The HydrousDB root client.
  *
- * Instantiate once and reuse throughout your app.
+ * Create once and reuse across your app:
  *
- * @example
- * import { HydrousClient } from 'hydrous';
+ * ```ts
+ * import { createClient } from 'hydrousdb';
  *
- * const hydrous = new HydrousClient({
- *   url:    'https://api.myapp.hydrous.app',
- *   apiKey: 'hk_live_…',
+ * const db = createClient({
+ *   url:               'https://api.myapp.hydrous.app',
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     documents: 'ssk_docs_…',
+ *   },
  * });
+ * ```
  */
 declare class HydrousClient {
-    /** Authentication — sign up, sign in, sign out, session management */
+    /** Auth — sign up, sign in, sign out, session management */
     readonly auth: AuthClient;
     /** Records — insert, select, update, delete structured data */
     readonly records: RecordsClient;
-    /** Analytics — track events, query event history */
+    /** Analytics — track events and query history */
     readonly analytics: AnalyticsClient;
     /**
-     * Storage — upload, download, list, move, delete files.
+     * Storage — call with the name of the key you want.
      *
-     * Every method takes a **bucket key** (`ssk_…`) as its **first argument**.
+     * ```ts
+     * db.storage('avatars').upload(file, { path: 'user.jpg' })
+     * db.storage('documents').list({ prefix: 'invoices/' })
+     * db.storage('main').stats()
+     * ```
      */
-    readonly storage: StorageClient;
+    readonly storage: CallableStorage;
     constructor(config: HydrousConfig);
 }
 
-/** Shorthand helper: creates a simple equality filter */
-declare function eq(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "not equal" filter */
-declare function neq(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "greater than" filter */
-declare function gt(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "less than" filter */
-declare function lt(field: string, value: unknown): Filter;
-/** Shorthand helper: creates an "in array" filter */
-declare function inArray(field: string, value: unknown[]): Filter;
+/**
+ * StorageManager is the object exposed as `db.storage`.
+ *
+ * Call `.use(keyName)` — or use the shorthand `db.storage('keyName')` which
+ * the main HydrousClient wires up as a Proxy — to get a scoped storage client
+ * bound to that key.
+ *
+ * ```ts
+ * db.storage('main').upload(file)
+ * db.storage('avatars').list()
+ * db.storage('documents').download('report.pdf')
+ * ```
+ */
+declare class StorageManager {
+    private readonly baseUrl;
+    private readonly _keys;
+    private readonly cache;
+    constructor(config: HydrousConfig);
+    /**
+     * Get a storage client scoped to a named key.
+     *
+     * @param keyName - Must match a property you declared in `storageKeys`
+     *
+     * @example
+     * const avatarStore   = db.storage('avatars');
+     * const documentStore = db.storage('documents');
+     *
+     * await avatarStore.upload(file, { path: 'users/alice.jpg' });
+     * const list = await documentStore.list({ prefix: 'invoices/' });
+     */
+    use(keyName: string): ScopedStorageClient;
+    /** Return the names of all configured storage keys */
+    keyNames(): string[];
+}
+
+declare const eq: (field: string, value: unknown) => Filter;
+declare const neq: (field: string, value: unknown) => Filter;
+declare const gt: (field: string, value: unknown) => Filter;
+declare const lt: (field: string, value: unknown) => Filter;
+declare const gte: (field: string, value: unknown) => Filter;
+declare const lte: (field: string, value: unknown) => Filter;
+declare const inArray: (field: string, value: unknown[]) => Filter;
 
-declare class HydrousSDKError extends Error {
+declare class HydrousDBError extends Error {
     readonly code: string;
     readonly status: number | undefined;
     constructor(message: string, code?: string, status?: number);
 }
-declare function isHydrousError(err: unknown): err is HydrousSDKError;
+declare function isHydrousError(err: unknown): err is HydrousDBError;
 
 /**
- * Create and return a `HydrousClient` instance.
+ * Create a HydrousDB client.
  *
  * @example
- * import { createClient } from 'hydrous';
+ * import { createClient } from 'hydrousdb';
  *
- * const hydrous = createClient({
- *   url:    'https://api.myapp.hydrous.app',
- *   apiKey: 'hk_live_…',
+ * const db = createClient({
+ *   url:               'https://api.myapp.hydrous.app',
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     documents: 'ssk_docs_…',
+ *   },
  * });
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
-export { AnalyticsClient, type AnalyticsEvent, type AnalyticsQueryOptions, AuthClient, type AuthSession, type AuthUser, type BatchDownloadFile, type BatchDownloadOptions, type BatchUploadOptions, type BatchUploadResult, type BucketKey, type DownloadProgress, type FileMetadata, type Filter, type FilterOperator, HydrousClient, type HydrousConfig, type HydrousError, type HydrousResponse, HydrousSDKError, type ListOptions, type ListResult, type QueryOptions, type RecordResponse, RecordsClient, type SignInOptions, type SignUpOptions, type SignedUrlOptions, type SignedUrlResult, type SingleRecordResponse, StorageClient, type StorageItem, type StorageStats, type TrackEventOptions, type UploadOptions, type UploadProgress, type UploadResult, type UploadStage, createClient, eq, gt, inArray, isHydrousError, lt, neq };
+export { AnalyticsClient, type AnalyticsEvent, type AnalyticsQueryOptions, AuthClient, type AuthSession, type AuthUser, type BatchDownloadFile, type BatchDownloadOptions, type BatchUploadOptions, type BatchUploadResult, type CallableStorage, type DownloadProgress, type FileMetadata, type Filter, type FilterOperator, HydrousClient, type HydrousConfig, HydrousDBError, type HydrousError, type HydrousResponse, type ListOptions, type ListResult, type QueryOptions, type RecordResponse, RecordsClient, ScopedStorageClient, type SignInOptions, type SignUpOptions, type SignedUrlOptions, type SignedUrlResult, type SingleRecordResponse, type StorageItem, type StorageKeys, StorageManager, type StorageStats, type TrackEventOptions, type UploadOptions, type UploadProgress, type UploadResult, type UploadStage, createClient, eq, gt, gte, inArray, isHydrousError, lt, lte, neq };