hydrousdb 3.0.2 → 3.2.0

package/dist/index.d.ts

@@ -1,68 +1,34 @@
 interface RequestOptions {
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    method: string;
     body?: unknown;
+    rawBody?: FormData | Uint8Array | ArrayBuffer;
     headers?: Record<string, string>;
-    rawBody?: string | FormData | Uint8Array<ArrayBuffer>;
-    contentType?: string;
 }
 declare class HttpClient {
     private readonly baseUrl;
     constructor(baseUrl: string);
-    request<T = unknown>(path: string, apiKeyOrOpts?: string | RequestOptions, opts?: RequestOptions): Promise<T>;
-    get<T = unknown>(path: string, apiKey?: string, headers?: Record<string, string>): Promise<T>;
-    post<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    put<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    patch<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    delete<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    putToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+    request<T>(path: string, options: RequestOptions): Promise<T>;
+    get<T>(path: string, apiKey?: string, extraHeaders?: Record<string, string>): Promise<T>;
+    post<T>(path: string, apiKey: string, body?: unknown): Promise<T>;
+    put<T>(path: string, apiKey: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, apiKey: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, apiKey: string, body?: unknown): Promise<T>;
+    /**
+     * Upload directly to a signed GCS URL (no auth headers — signed URL is self-authenticating).
+     * Supports optional progress tracking via XHR in browser environments.
+     */
+    putToSignedUrl(signedUrl: string, data: Blob | Uint8Array | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
 }
 
-/**
- * Storage keys map — one named key per storage bucket/permission scope.
- * Keys start with `ssk_`. You can define as many as you need.
- *
- * @example
- * ```ts
- * storageKeys: {
- *   main:      'ssk_main_…',
- *   avatars:   'ssk_avatars_…',
- *   documents: 'ssk_docs_…',
- * }
- * ```
- */
 type StorageKeys = Record<string, string>;
 interface HydrousConfig {
-    /**
-     * Auth service key (starts with `hk_auth_`).
-     * Used exclusively for all `/auth/*` routes — signup, login, sessions, etc.
-     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
-     */
+    /** Auth service key (starts with `hk_auth_`). */
     authKey: string;
-    /**
-     * Bucket security key (starts with `hk_bucket_`).
-     * Used for all `/records/*` and `/analytics/*` routes.
-     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
-     */
+    /** Bucket security key (starts with `hk_bucket_`). Used for records + analytics. */
     bucketSecurityKey: string;
-    /**
-     * Named storage keys (each starts with `ssk_`).
-     * Define one key per storage bucket/permission scope.
-     * Pass the name of the key you want when calling `db.storage('keyName')`.
-     *
-     * @example
-     * ```ts
-     * storageKeys: {
-     *   main:      'ssk_main_…',      // default general-purpose bucket
-     *   avatars:   'ssk_avatars_…',   // user avatar uploads
-     *   documents: 'ssk_docs_…',      // private documents
-     * }
-     * ```
-     */
+    /** Named storage keys (each starts with `ssk_`). */
     storageKeys: StorageKeys;
-    /**
-     * Override the API base URL. Defaults to the official HydrousDB endpoint.
-     * You almost never need to set this.
-     */
+    /** Override the API base URL. Defaults to the official HydrousDB endpoint. */
     baseUrl?: string;
 }
 interface SignupOptions {
@@ -103,24 +69,26 @@ interface AuthResult {
 interface UpdateUserOptions {
     sessionId: string;
     userId: string;
-    data: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
+    /** Fields to update — nested under `updates` when sent to the server. */
+    updates: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
 }
 interface ChangePasswordOptions {
     sessionId: string;
     userId: string;
+    /** Maps to `oldPassword` on the server. */
     currentPassword: string;
     newPassword: string;
 }
 interface ListUsersOptions {
     sessionId: string;
     limit?: number;
-    offset?: number;
+    /** Cursor for the next page (URL-encoded value returned by the previous call). */
+    cursor?: string;
 }
 interface ListUsersResult {
     users: UserRecord[];
-    total: number;
-    limit: number;
-    offset: number;
+    hasMore: boolean;
+    nextCursor: string | null;
 }
 type RecordData = Record<string, unknown>;
 interface RecordResult {
@@ -161,12 +129,34 @@ interface RecordHistoryEntry {
     createdAt: number;
     data: RecordData;
 }
+/** Options for creating a record — includes queryable fields for filtering. */
+interface CreateRecordOptions {
+    /**
+     * Fields that should be indexed for server-side filtering.
+     * Only fields listed here will be queryable via `query({ filters: [...] })`.
+     */
+    queryableFields?: string[];
+    /** Email of the user performing the action (for audit trails). */
+    userEmail?: string;
+    /**
+     * Assign a custom record ID instead of an auto-generated one.
+     * If the ID already exists, the record will be upserted.
+     */
+    customRecordId?: string;
+}
+/** Options for batch-creating records. */
+interface BatchCreateOptions {
+    /** Fields to index for filtering — applied to all records in the batch. */
+    queryableFields?: string[];
+    /** Email of the user performing the action. */
+    userEmail?: string;
+}
 interface UploadOptions {
-    /** Set to true to make the file publicly accessible without authentication. */
+    /** Make the file publicly accessible without authentication. */
     isPublic?: boolean;
-    /** Set to true to overwrite an existing file at the same path. */
+    /** Overwrite an existing file at the same path. */
     overwrite?: boolean;
-    /** MIME type of the file. Auto-detected if omitted. */
+    /** MIME type of the file. Auto-detected from extension if omitted. */
     mimeType?: string;
     /** TTL in seconds for the signed upload URL (default 900 = 15 min). */
     expiresInSeconds?: number;
@@ -195,6 +185,7 @@ interface ListOptions {
 interface FileEntry {
     name: string;
     path: string;
+    type?: 'file' | 'folder';
     size?: number;
     mimeType?: string;
     isPublic?: boolean;
@@ -243,14 +234,27 @@ interface BatchUploadUrlResult {
         index: number;
     }>;
 }
+interface BatchDownloadResult {
+    succeeded: Array<{
+        index: number;
+        path: string;
+        mimeType: string;
+        size: number;
+        content: string;
+    }>;
+    failed: Array<{
+        index: number;
+        path: string;
+        error: string;
+        code?: string;
+    }>;
+}
 type QueryType = 'count' | 'distribution' | 'sum' | 'timeSeries' | 'fieldTimeSeries' | 'topN' | 'stats' | 'records' | 'multiMetric' | 'storageStats' | 'crossBucket';
 type Aggregation = 'sum' | 'avg' | 'min' | 'max' | 'count';
 type Granularity = 'hour' | 'day' | 'week' | 'month' | 'year';
 type SortOrder = 'asc' | 'desc';
 interface DateRange {
-    /** Start timestamp in milliseconds (Unix epoch). */
     start?: number;
-    /** End timestamp in milliseconds (Unix epoch). */
     end?: number;
 }
 interface AnalyticsFilter {
@@ -259,11 +263,8 @@ interface AnalyticsFilter {
     value: string | number | boolean;
 }
 interface MetricDefinition {
-    /** Field name in your records to aggregate. */
     field: string;
-    /** Alias used in the result object. Must be a safe identifier. */
     name: string;
-    /** Aggregation function. Defaults to 'count'. */
     aggregation?: Aggregation;
 }
 interface AnalyticsQuery {
@@ -282,7 +283,6 @@ interface AnalyticsQuery {
     order?: SortOrder;
     n?: number;
     metrics?: MetricDefinition[];
-    /** For crossBucket queries: list of bucket names to compare. */
     bucketKeys?: string[];
 }
 interface AnalyticsResult<T = unknown> {
@@ -340,10 +340,13 @@ interface CrossBucketRow {
  * AuthClient — full user authentication for a single bucket.
  * Uses the `authKey` (`hk_auth_…`) sent via `X-Api-Key` header.
  *
+ * All routes are under `/auth/:bucketKey/` — the bucketKey is the user bucket
+ * name you passed when calling `db.auth('bucketKey')`.
+ *
  * @example
  * ```ts
- * const db = createClient({ authKey: 'hk_auth_…', bucketSecurityKey: '…', storageKeys: { main: '…' } });
- * const auth = db.auth('my-app-users');
+ * const db   = createClient({ authKey: 'hk_auth_…', … });
+ * const auth = db.auth('app-users');
  * const { user, session } = await auth.signup({ email: 'alice@example.com', password: 'hunter2' });
  * ```
  */
@@ -358,12 +361,22 @@ declare class AuthClient {
     private delete;
     signup(options: SignupOptions): Promise<AuthResult>;
     login(options: LoginOptions): Promise<AuthResult>;
-    logout({ sessionId }: {
+    logout(options: {
         sessionId: string;
+        allDevices?: boolean;
     }): Promise<void>;
     refreshSession({ refreshToken }: {
         refreshToken: string;
     }): Promise<Session>;
+    validateSession({ sessionId }: {
+        sessionId: string;
+    }): Promise<{
+        user: UserRecord;
+        session: {
+            sessionId: string;
+            expiresAt: number;
+        };
+    }>;
     getUser({ userId }: {
         userId: string;
     }): Promise<UserRecord>;
@@ -377,14 +390,15 @@ declare class AuthClient {
         sessionId: string;
         userId: string;
     }): Promise<void>;
-    bulkDeleteUsers({ sessionId, userIds }: {
+    bulkDeleteUsers(options: {
         sessionId: string;
         userIds: string[];
+        hard?: boolean;
     }): Promise<{
-        deleted: number;
-        failed: string[];
+        succeeded: number;
+        failed: number;
     }>;
-    lockAccount({ sessionId, userId, duration }: {
+    lockAccount(options: {
         sessionId: string;
         userId: string;
         duration?: number;
@@ -413,49 +427,121 @@ declare class AuthClient {
 }
 
 /**
- * RecordsClient — CRUD + query for a single bucket.
+ * RecordsClient — typed CRUD + query + batch for a single bucket.
  * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
  *
  * @example
  * ```ts
- * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
- * const posts = db.records('blog-posts');
- * const post = await posts.create({ title: 'Hello World', status: 'draft' });
+ * interface Post { title: string; published: boolean }
+ * const posts = db.records<Post>('blog-posts');
+ * const post  = await posts.create({ title: 'Hello', published: false });
  * ```
  */
 declare class RecordsClient<T extends RecordData = RecordData> {
     private readonly http;
     private readonly bucketKey;
+    private readonly apiKey;
     private readonly basePath;
-    private readonly bucketKey_;
     constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
-    private get key();
-    create(data: T): Promise<T & RecordResult>;
+    /**
+     * Create a new record.
+     *
+     * @param data    The record fields to store.
+     * @param options Optional: queryableFields (for server-side filtering),
+     *                userEmail (audit trail), customRecordId (upsert by ID).
+     *
+     * @example
+     * ```ts
+     * const post = await posts.create(
+     *   { title: 'Hello', status: 'draft', authorId: 'u1' },
+     *   { queryableFields: ['status', 'authorId'], userEmail: 'alice@example.com' },
+     * );
+     * ```
+     */
+    create(data: T, options?: CreateRecordOptions): Promise<T & RecordResult>;
+    /**
+     * Get a single record by ID.
+     */
     get(id: string): Promise<T & RecordResult>;
+    /**
+     * Fully replace a record (PUT semantics).
+     */
     set(id: string, data: T): Promise<T & RecordResult>;
+    /**
+     * Partially update a record (PATCH semantics).
+     * By default merges with existing fields; set `merge: false` to replace.
+     * Supports write-filter sentinels: `{ __op: 'increment', delta: 1 }` etc.
+     */
     patch(id: string, data: Partial<T>, options?: PatchRecordOptions): Promise<T & RecordResult>;
+    /**
+     * Delete a record permanently.
+     */
     delete(id: string): Promise<void>;
-    batchCreate(items: T[]): Promise<(T & RecordResult)[]>;
+    /**
+     * Create multiple records in one request (max 500).
+     * Each record can include a `_customRecordId` field for upsert behaviour.
+     *
+     * @example
+     * ```ts
+     * const created = await posts.batchCreate(
+     *   [{ title: 'A' }, { title: 'B' }],
+     *   { queryableFields: ['title'], userEmail: 'alice@example.com' },
+     * );
+     * ```
+     */
+    batchCreate(items: T[], options?: BatchCreateOptions): Promise<(T & RecordResult)[]>;
+    /**
+     * Delete multiple records in one request (max 500).
+     */
     batchDelete(ids: string[]): Promise<{
         deleted: number;
         failed: string[];
     }>;
+    /**
+     * Query records with optional filters, sorting, and pagination.
+     *
+     * @example
+     * ```ts
+     * const { records, hasMore, nextCursor } = await posts.query({
+     *   filters: [{ field: 'status', op: '==', value: 'published' }],
+     *   orderBy: 'createdAt',
+     *   order:   'desc',
+     *   limit:   20,
+     * });
+     * ```
+     */
     query(options?: QueryOptions): Promise<QueryResult<T>>;
+    /**
+     * Get all records matching the given options (no filter support — use `query()` for filters).
+     */
     getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
+    /**
+     * Count records matching the given filters.
+     */
     count(filters?: QueryOptions['filters']): Promise<number>;
+    /**
+     * Get the version history of a record.
+     */
     getHistory(id: string): Promise<RecordHistoryEntry[]>;
+    /**
+     * Restore a record to a previous version.
+     */
     restoreVersion(id: string, version: number): Promise<T & RecordResult>;
 }
 
 /**
- * AnalyticsClient — BigQuery-powered aggregations for a bucket.
+ * AnalyticsClient — BigQuery-powered aggregations for a single bucket.
  * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
  *
+ * All methods POST a `queryType` body to `POST /analytics/:bucketKey`.
+ * The `dateRange` is passed as `{ start, end }` ms timestamps — the server
+ * converts them to ISO date strings internally.
+ *
  * @example
  * ```ts
- * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
  * const analytics = db.analytics('orders');
  * const { count } = await analytics.count();
+ * const top5      = await analytics.topN({ field: 'country', n: 5 });
  * ```
  */
 declare class AnalyticsClient {
@@ -464,31 +550,37 @@ declare class AnalyticsClient {
     private readonly basePath;
     constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
     private run;
+    /** Count all records, optionally within a date range. */
     count(opts?: {
         dateRange?: DateRange;
     }): Promise<CountResult>;
+    /** Get value distribution for a field (e.g. how many records per status). */
     distribution(opts: {
         field: string;
         limit?: number;
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<DistributionRow[]>;
+    /** Sum a numeric field, optionally grouped by another field. */
     sum(opts: {
         field: string;
         groupBy?: string;
         limit?: number;
         dateRange?: DateRange;
     }): Promise<SumRow[]>;
+    /** Count of records over time, bucketed by granularity. */
     timeSeries(opts?: {
         granularity?: Granularity;
         dateRange?: DateRange;
     }): Promise<TimeSeriesRow[]>;
+    /** Aggregate a numeric field over time. */
     fieldTimeSeries(opts: {
         field: string;
         aggregation?: Aggregation;
         granularity?: Granularity;
         dateRange?: DateRange;
     }): Promise<FieldTimeSeriesRow[]>;
+    /** Top N values for a field by count. */
     topN(opts: {
         field: string;
         n?: number;
@@ -496,10 +588,12 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<TopNRow[]>;
+    /** Statistical summary (min, max, avg, sum, count, stddev) for a numeric field. */
     stats(opts: {
         field: string;
         dateRange?: DateRange;
     }): Promise<FieldStats>;
+    /** Fetch filtered records via the analytics engine (bypasses Firestore pagination). */
     records<T extends RecordData = RecordData>(opts?: {
         filters?: AnalyticsFilter[];
         selectFields?: string[];
@@ -509,96 +603,84 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<(T & RecordResult)[]>;
+    /** Compute multiple aggregations in a single request. */
     multiMetric(opts: {
         metrics: MetricDefinition[];
         dateRange?: DateRange;
     }): Promise<MultiMetricResult>;
+    /** Storage usage stats for the bucket (record count, bytes, avg/min/max size). */
     storageStats(opts?: {
         dateRange?: DateRange;
     }): Promise<StorageStatsResult>;
+    /**
+     * Compare a metric across multiple buckets in one query.
+     * The caller's key must have read access to every bucket in `bucketKeys`.
+     */
     crossBucket(opts: {
         bucketKeys: string[];
         field: string;
         aggregation?: Aggregation;
         dateRange?: DateRange;
     }): Promise<CrossBucketRow[]>;
+    /**
+     * Raw query — use this when none of the typed helpers cover your use case.
+     */
     query<T = unknown>(query: AnalyticsQuery): Promise<AnalyticsResult<T>>;
 }
 
 /**
  * StorageManager — upload, download, list, move, copy, and delete files.
  * Uses an `X-Storage-Key` (`ssk_…`) header — separate from auth and bucket keys.
- * Each key is scoped to a specific storage bucket and permission set.
  *
- * Get a StorageManager via `db.storage('keyName')` where the key name
- * matches one of the keys you defined in `storageKeys` when calling `createClient`.
+ * Get a StorageManager via `db.storage('keyName')` where the name matches
+ * one of the keys defined in `storageKeys` when calling `createClient`.
  *
  * @example
  * ```ts
- * const db = createClient({ authKey: '…', bucketSecurityKey: '…', storageKeys: { avatars: 'ssk_avatars_…' } });
  * const avatars = db.storage('avatars');
- * const result = await avatars.upload(file, 'alice.jpg', { isPublic: true });
+ * const result  = await avatars.upload(file, 'alice.jpg', { isPublic: true });
+ * console.log(result.publicUrl);
  * ```
  */
 declare class StorageManager {
     private readonly http;
     private readonly storageKey;
-    private readonly basePath;
+    readonly basePath = "/storage";
     constructor(http: HttpClient, storageKey: string);
-    /** Headers for all storage requests — uses X-Storage-Key, not X-Api-Key. */
     private get authHeaders();
     /**
      * Upload a file to storage in one step (server-buffered, up to 500 MB).
-     * For files >10 MB or when you need upload progress, use `getUploadUrl()` instead.
-     *
-     * @param data     File data as a Blob, Buffer, Uint8Array, or ArrayBuffer.
-     * @param path     Destination path in your storage (e.g. `"avatars/alice.jpg"`).
-     * @param options  Upload options: isPublic, overwrite, mimeType.
+     * For files >10 MB or when upload progress is needed, use `getUploadUrl()`.
      *
      * @example
      * ```ts
-     * // Upload a public avatar
      * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
-     * console.log(result.publicUrl); // → https://...
-     *
-     * // Upload a private document
-     * const result = await storage.upload(pdfBuffer, 'docs/contract.pdf');
-     * console.log(result.downloadUrl); // → /storage/download/docs/contract.pdf
+     * console.log(result.publicUrl);
      * ```
      */
-    upload(data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
+    upload(data: Blob | Uint8Array | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
     /**
-     * Upload raw JSON or plain text data as a file.
+     * Upload raw JSON or plain-text data as a file.
      *
      * @example
      * ```ts
-     * const result = await storage.uploadRaw(
-     *   { config: { theme: 'dark' } },
-     *   'settings/user-config.json',
-     *   { isPublic: false },
-     * );
+     * await storage.uploadRaw({ theme: 'dark' }, 'settings/config.json');
      * ```
      */
     uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
     /**
-     * Step 1 of the recommended upload flow.
-     * Get a signed URL to upload directly to GCS from the client (supports progress).
+     * Step 1 — get a signed GCS URL to upload directly from the client.
+     * Supports upload progress via `uploadToSignedUrl()`.
      *
      * @example
      * ```ts
      * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
-     *   path: 'videos/intro.mp4',
+     *   path:     'videos/intro.mp4',
      *   mimeType: 'video/mp4',
-     *   size: file.size,
+     *   size:     file.size,
      *   isPublic: true,
      * });
-     *
-     * // Upload using XHR for progress tracking
-     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (pct) => {
-     *   console.log(`${pct}% uploaded`);
-     * });
-     *
-     * // Step 3: confirm
+     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => console.log(pct + '%'));
      * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
      * ```
      */
@@ -611,28 +693,12 @@ declare class StorageManager {
         expiresInSeconds?: number;
     }): Promise<UploadUrlResult>;
     /**
-     * Upload data directly to a signed GCS URL (no auth headers needed).
-     * Optionally tracks progress via a callback.
-     *
-     * @param signedUrl  The URL returned by `getUploadUrl()`.
-     * @param data       File data.
-     * @param mimeType   Must match what was used in `getUploadUrl()`.
-     * @param onProgress Optional callback called with 0–100 progress percentage.
+     * Step 2 — upload data directly to a signed GCS URL.
+     * Supports progress tracking in browser environments.
      */
-    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
     /**
-     * Step 3 of the recommended upload flow.
-     * Confirm a direct upload and register metadata on the server.
-     *
-     * @example
-     * ```ts
-     * const result = await storage.confirmUpload({
-     *   path: 'videos/intro.mp4',
-     *   mimeType: 'video/mp4',
-     *   isPublic: true,
-     * });
-     * console.log(result.publicUrl);
-     * ```
+     * Step 3 — confirm a direct upload and register metadata on the server.
      */
     confirmUpload(opts: {
         path: string;
@@ -640,16 +706,15 @@ declare class StorageManager {
         isPublic?: boolean;
     }): Promise<UploadResult>;
     /**
-     * Get signed upload URLs for multiple files at once.
+     * Get signed upload URLs for multiple files at once (max 50).
+     * Server returns `{ succeeded, failed }` — only succeeded items have URLs.
      *
      * @example
      * ```ts
      * const { files } = await storage.getBatchUploadUrls([
-     *   { path: 'images/photo1.jpg', mimeType: 'image/jpeg', size: 204800 },
-     *   { path: 'images/photo2.jpg', mimeType: 'image/jpeg', size: 153600 },
+     *   { path: 'images/a.jpg', mimeType: 'image/jpeg', size: 204800 },
+     *   { path: 'images/b.jpg', mimeType: 'image/jpeg', size: 153600 },
      * ]);
-     *
-     * // Upload each file and confirm
      * for (const f of files) {
      *   await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
      *   await storage.confirmUpload({ path: f.path, mimeType: f.mimeType });
@@ -659,93 +724,65 @@ declare class StorageManager {
     getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
     /**
      * Confirm multiple direct uploads at once.
+     * Returns both succeeded and failed results.
      */
     batchConfirmUploads(items: Array<{
         path: string;
         mimeType: string;
         isPublic?: boolean;
-    }>): Promise<UploadResult[]>;
+    }>): Promise<{
+        succeeded: UploadResult[];
+        failed: Array<{
+            path: string;
+            error: string;
+        }>;
+    }>;
     /**
      * Download a private file as an ArrayBuffer.
      * For public files, use the `publicUrl` directly — no SDK needed.
-     *
-     * @example
-     * ```ts
-     * const buffer = await storage.download('docs/contract.pdf');
-     * const blob = new Blob([buffer], { type: 'application/pdf' });
-     * // Open in browser:
-     * window.open(URL.createObjectURL(blob));
-     * ```
      */
     download(path: string): Promise<ArrayBuffer>;
     /**
-     * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+     * Download multiple files at once (max 20).
+     * Returns a structured result with succeeded and failed items.
+     * Each succeeded item includes the file content as a base64 string.
      *
      * @example
      * ```ts
-     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * const { succeeded, failed } = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * for (const f of succeeded) {
+     *   const bytes = Buffer.from(f.content, 'base64');
+     * }
      * ```
      */
-    batchDownload(paths: string[]): Promise<Record<string, string>>;
+    batchDownload(paths: string[]): Promise<BatchDownloadResult>;
     /**
      * List files and folders at a given path prefix.
+     * Returns separate `files` and `folders` arrays for easy consumption.
      *
      * @example
      * ```ts
-     * // List everything in the root
-     * const { files, folders } = await storage.list();
-     *
-     * // List a specific folder
-     * const { files, folders, hasMore, nextCursor } = await storage.list({
-     *   prefix: 'avatars/',
-     *   limit: 20,
-     * });
-     *
-     * // Next page
+     * const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/', limit: 20 });
      * const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
      * ```
      */
     list(opts?: ListOptions): Promise<ListResult>;
     /**
-     * Get metadata for a file (size, MIME type, visibility, URLs).
-     *
-     * @example
-     * ```ts
-     * const meta = await storage.getMetadata('avatars/alice.jpg');
-     * console.log(meta.size, meta.isPublic, meta.publicUrl);
-     * ```
+     * Get metadata for a file: size, MIME type, visibility, URLs.
      */
     getMetadata(path: string): Promise<FileMetadata>;
     /**
      * Generate a time-limited download URL for a private file.
-     * The URL can be shared externally without requiring an `X-Storage-Key`.
-     *
-     * > **Note:** Downloads via signed URLs bypass the server, so download stats
-     * > are NOT tracked. Use `downloadUrl` for tracked downloads.
+     * Can be shared externally without requiring an `X-Storage-Key`.
      *
-     * @param path       Path to the file.
-     * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+     * > Note: Downloads via signed URLs bypass the server — download stats are NOT tracked.
      *
-     * @example
-     * ```ts
-     * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
-     * // Share signedUrl with the recipient — it expires in 30 minutes.
-     * ```
+     * @param path      File path.
+     * @param expiresIn URL lifetime in seconds (default 3600 = 1 hour).
      */
     getSignedUrl(path: string, expiresIn?: number): Promise<SignedUrlResult>;
     /**
      * Change a file's visibility between public and private after upload.
-     *
-     * @example
-     * ```ts
-     * // Make a file public
-     * const result = await storage.setVisibility('avatars/alice.jpg', true);
-     * console.log(result.publicUrl); // CDN URL
-     *
-     * // Make a file private
-     * const result = await storage.setVisibility('avatars/alice.jpg', false);
-     * console.log(result.downloadUrl); // Auth-required URL
-     * ```
      */
     setVisibility(path: string, isPublic: boolean): Promise<{
         path: string;
@@ -753,81 +790,20 @@ declare class StorageManager {
         publicUrl: string | null;
         downloadUrl: string | null;
     }>;
-    /**
-     * Create a folder (a GCS prefix placeholder).
-     *
-     * @example
-     * ```ts
-     * await storage.createFolder('uploads/2025/');
-     * ```
-     */
     createFolder(path: string): Promise<{
         path: string;
     }>;
-    /**
-     * Delete a single file.
-     *
-     * @example
-     * ```ts
-     * await storage.deleteFile('avatars/old-avatar.jpg');
-     * ```
-     */
     deleteFile(path: string): Promise<void>;
-    /**
-     * Delete a folder and all its contents recursively.
-     *
-     * @example
-     * ```ts
-     * await storage.deleteFolder('temp/');
-     * ```
-     */
     deleteFolder(path: string): Promise<void>;
-    /**
-     * Move or rename a file.
-     *
-     * @example
-     * ```ts
-     * // Rename
-     * await storage.move('docs/draft.pdf', 'docs/final.pdf');
-     * // Move to a different folder
-     * await storage.move('inbox/report.xlsx', 'archive/2025/report.xlsx');
-     * ```
-     */
     move(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
-    /**
-     * Copy a file to a new path.
-     *
-     * @example
-     * ```ts
-     * await storage.copy('templates/base.html', 'sites/my-site/index.html');
-     * ```
-     */
     copy(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
-    /**
-     * Get storage statistics for your key: total files, bytes, operation counts.
-     *
-     * @example
-     * ```ts
-     * const stats = await storage.getStats();
-     * console.log(`${stats.totalFiles} files, ${(stats.totalBytes / 1e6).toFixed(1)} MB`);
-     * ```
-     */
     getStats(): Promise<StorageStats>;
-    /**
-     * Ping the storage service. No authentication required.
-     *
-     * @example
-     * ```ts
-     * const info = await storage.info();
-     * // → { ok: true, storageRoot: 'hydrous-storage' }
-     * ```
-     */
     info(): Promise<{
         ok: boolean;
         storageRoot: string;
@@ -835,89 +811,98 @@ declare class StorageManager {
 }
 
 /**
- * ScopedStorage — a StorageManager pre-scoped to a specific folder prefix.
+ * ScopedStorage — a path-prefixed view over a StorageManager.
+ * All paths you pass are automatically prefixed with the scope.
  *
- * All paths are automatically prepended with the scope, so you never
- * have to repeat the folder name.
+ * Obtain via `db.storage('keyName').scope('prefix/')`.
  *
  * @example
  * ```ts
- * const db = createClient({ securityKey: 'sk_...' });
+ * const userDocs = db.storage('documents').scope(`users/${userId}/`);
  *
- * // All operations in the "avatars/" folder
- * const avatars = db.storage.scope('avatars');
+ * // Uploads to: users/{userId}/contract.pdf
+ * await userDocs.upload(pdfBuffer, 'contract.pdf');
  *
- * await avatars.upload(file, 'alice.jpg');       // → "avatars/alice.jpg"
- * const list = await avatars.list();             // → files under "avatars/"
- * await avatars.deleteFile('alice.jpg');         // → deletes "avatars/alice.jpg"
+ * // Lists:      users/{userId}/
+ * const { files } = await userDocs.list();
  * ```
  */
 declare class ScopedStorage {
     private readonly manager;
     private readonly prefix;
     constructor(manager: StorageManager, prefix: string);
-    private scopedPath;
-    /** Upload a file within the scoped folder. */
-    upload(data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
-    /** Upload raw JSON or text within the scoped folder. */
+    private p;
+    upload(data: Blob | Uint8Array | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
     uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
-    /** Get a signed upload URL for a file within the scoped folder. */
     getUploadUrl(opts: {
         path: string;
         mimeType: string;
         size: number;
         isPublic?: boolean;
         overwrite?: boolean;
+        expiresInSeconds?: number;
     }): Promise<UploadUrlResult>;
-    /** Confirm a direct upload within the scoped folder. */
+    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
     confirmUpload(opts: {
         path: string;
         mimeType: string;
         isPublic?: boolean;
     }): Promise<UploadResult>;
-    /** Download a file within the scoped folder. */
+    getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
+    batchConfirmUploads(items: Array<{
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }>): Promise<{
+        succeeded: UploadResult[];
+        failed: Array<{
+            path: string;
+            error: string;
+        }>;
+    }>;
     download(path: string): Promise<ArrayBuffer>;
+    batchDownload(paths: string[]): Promise<BatchDownloadResult>;
     /**
-     * List files within the scoped folder.
-     * `prefix` in options is relative to the scope.
+     * List files within this scope. The `prefix` option is relative to the scope root.
+     *
+     * @example
+     * ```ts
+     * const userDocs = storage.scope('users/alice/');
+     * // Lists users/alice/docs/
+     * const { files } = await userDocs.list({ prefix: 'docs/' });
+     * ```
      */
     list(opts?: ListOptions): Promise<ListResult>;
-    /** Get metadata for a file within the scoped folder. */
     getMetadata(path: string): Promise<FileMetadata>;
-    /** Get a time-limited signed URL for a file within the scoped folder. */
     getSignedUrl(path: string, expiresIn?: number): Promise<SignedUrlResult>;
-    /** Change visibility of a file within the scoped folder. */
     setVisibility(path: string, isPublic: boolean): Promise<{
         path: string;
         isPublic: boolean;
         publicUrl: string | null;
         downloadUrl: string | null;
     }>;
-    /** Delete a file within the scoped folder. */
+    createFolder(path: string): Promise<{
+        path: string;
+    }>;
     deleteFile(path: string): Promise<void>;
-    /** Delete a sub-folder within the scoped folder. */
     deleteFolder(path: string): Promise<void>;
-    /** Move a file within the scoped folder. */
     move(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
-    /** Copy a file within the scoped folder. */
     copy(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
-    /** Create a sub-folder within the scoped folder. */
-    createFolder(path: string): Promise<{
-        path: string;
-    }>;
+    getStats(): Promise<StorageStats>;
     /**
-     * Create a further-scoped instance nested within this scope.
+     * Create a deeper scope within this one.
      *
      * @example
      * ```ts
-     * const uploads = db.storage.scope('user-uploads');
-     * const images = uploads.scope('images');   // → "user-uploads/images/"
+     * const user    = storage.scope('users/alice/');
+     * const userDocs = user.scope('docs/');
+     * // Effective prefix: users/alice/docs/
      * ```
      */
     scope(subPrefix: string): ScopedStorage;
@@ -926,35 +911,30 @@ declare class ScopedStorage {
 /**
  * HydrousClient — the main entry point for the HydrousDB SDK.
  *
- * Each service uses its own dedicated key:
+ * Each service uses its own dedicated API key:
  * - `authKey`            (`hk_auth_…`)   → `db.auth('bucket')`
  * - `bucketSecurityKey`  (`hk_bucket_…`) → `db.records('bucket')` + `db.analytics('bucket')`
  * - `storageKeys`        (`ssk_…`)       → `db.storage('keyName')`
  *
+ * Sub-clients are cached — calling `db.records('posts')` twice returns the same instance.
+ *
  * @example
  * ```ts
  * import { createClient } from 'hydrousdb';
  *
  * const db = createClient({
- *   authKey:           'hk_auth_…',
- *   bucketSecurityKey: 'hk_bucket_…',
+ *   authKey:           process.env.HYDROUS_AUTH_KEY!,
+ *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
  *   storageKeys: {
- *     main:      'ssk_main_…',
- *     avatars:   'ssk_avatars_…',
- *     documents: 'ssk_docs_…',
+ *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+ *     documents: process.env.HYDROUS_STORAGE_DOCS!,
  *   },
  * });
  *
- * // Records & Analytics — use bucketSecurityKey automatically
- * const posts     = db.records('blog-posts');
+ * const posts    = db.records('blog-posts');
+ * const auth     = db.auth('app-users');
  * const analytics = db.analytics('orders');
- *
- * // Auth — uses authKey automatically
- * const auth = db.auth('app-users');
- *
- * // Storage — pick which key to use by name
- * const avatarStorage   = db.storage('avatars');
- * const documentStorage = db.storage('documents');
+ * const avatars  = db.storage('avatars');
  * ```
  */
 declare class HydrousClient {
@@ -969,19 +949,20 @@ declare class HydrousClient {
     constructor(config: HydrousConfig);
     /**
      * Get a typed records client for the named bucket.
-     * Uses your `bucketSecurityKey` automatically.
      *
      * @example
      * ```ts
      * interface Post { title: string; published: boolean }
      * const posts = db.records<Post>('blog-posts');
-     * const post = await posts.create({ title: 'Hello', published: false });
+     * const post  = await posts.create(
+     *   { title: 'Hello', published: false },
+     *   { queryableFields: ['published'] },
+     * );
      * ```
      */
     records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
     /**
      * Get an auth client for the named user bucket.
-     * Uses your `authKey` automatically.
      *
      * @example
      * ```ts
@@ -992,7 +973,6 @@ declare class HydrousClient {
     auth(bucketKey: string): AuthClient;
     /**
      * Get an analytics client for the named bucket.
-     * Uses your `bucketSecurityKey` automatically.
      *
      * @example
      * ```ts
@@ -1003,21 +983,16 @@ declare class HydrousClient {
     analytics(bucketKey: string): AnalyticsClient;
     /**
      * Get a storage manager for the named storage key.
-     * The name must match a key you defined in `storageKeys` when calling `createClient`.
-     * Uses the corresponding `ssk_…` key automatically via `X-Storage-Key` header.
+     * The name must match a key defined in `storageKeys` when calling `createClient`.
      *
-     * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
+     * Attach `.scope(prefix)` to namespace all operations under a path prefix.
      *
      * @example
      * ```ts
-     * const avatars   = db.storage('avatars');
-     * const documents = db.storage('documents');
+     * const avatars  = db.storage('avatars');
+     * const userDocs = db.storage('documents').scope(`users/${userId}/`);
      *
-     * // Upload to avatars bucket
      * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-     *
-     * // Scope to a sub-folder
-     * const userDocs = db.storage('documents').scope(`users/${userId}`);
      * await userDocs.upload(pdfBuffer, 'contract.pdf');
      * ```
      */
@@ -1035,24 +1010,16 @@ declare class HydrousClient {
  * const db = createClient({
  *   authKey:           process.env.HYDROUS_AUTH_KEY!,
  *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
- *   storageKeys: {
- *     main:      process.env.HYDROUS_STORAGE_MAIN!,
- *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
- *     documents: process.env.HYDROUS_STORAGE_DOCS!,
- *   },
+ *   storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
  * });
  * ```
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
 declare class HydrousError extends Error {
-    /** Machine-readable error code returned by the API. */
     readonly code: string;
-    /** HTTP status code (if applicable). */
     readonly status?: number;
-    /** The original request ID for support tracing. */
     readonly requestId?: string;
-    /** Additional validation details. */
     readonly details?: string[];
     constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
     toString(): string;
@@ -1077,4 +1044,4 @@ declare class NetworkError extends HydrousError {
     constructor(message: string, cause?: unknown);
 }
 
-export { type Aggregation, AnalyticsClient, AnalyticsError, type AnalyticsFilter, type AnalyticsQuery, type AnalyticsResult, AuthClient, AuthError, type AuthResult, type BatchUploadItem, type BatchUploadUrlResult, type ChangePasswordOptions, type CountResult, type CrossBucketRow, type DateRange, type DistributionRow, type FieldStats, type FieldTimeSeriesRow, type FileEntry, type FileMetadata, type Granularity, HydrousClient, type HydrousConfig, HydrousError, type ListOptions, type ListResult, type ListUsersOptions, type ListUsersResult, type LoginOptions, type MetricDefinition, type MultiMetricResult, NetworkError, type PatchRecordOptions, type QueryFilter, type QueryOptions, type QueryResult, type QueryType, type RecordData, RecordError, type RecordHistoryEntry, type RecordResult, RecordsClient, ScopedStorage, type Session, type SignedUrlResult, type SignupOptions, type SortOrder, StorageError, StorageManager, type StorageStats, type StorageStatsResult, type SumRow, type TimeSeriesRow, type TopNRow, type UpdateUserOptions, type UploadOptions, type UploadResult, type UploadUrlResult, type UserRecord, ValidationError, createClient };
+export { type Aggregation, AnalyticsClient, AnalyticsError, type AnalyticsFilter, type AnalyticsQuery, type AnalyticsResult, AuthClient, AuthError, type AuthResult, type BatchCreateOptions, type BatchDownloadResult, type BatchUploadItem, type BatchUploadUrlResult, type ChangePasswordOptions, type CountResult, type CreateRecordOptions, type CrossBucketRow, type DateRange, type DistributionRow, type FieldStats, type FieldTimeSeriesRow, type FileEntry, type FileMetadata, type Granularity, HydrousClient, type HydrousConfig, HydrousError, type ListOptions, type ListResult, type ListUsersOptions, type ListUsersResult, type LoginOptions, type MetricDefinition, type MultiMetricResult, NetworkError, type PatchRecordOptions, type QueryFilter, type QueryOptions, type QueryResult, type QueryType, type RecordData, RecordError, type RecordHistoryEntry, type RecordResult, RecordsClient, ScopedStorage, type Session, type SignedUrlResult, type SignupOptions, type SortOrder, StorageError, type StorageKeys, StorageManager, type StorageStats, type StorageStatsResult, type SumRow, type TimeSeriesRow, type TopNRow, type UpdateUserOptions, type UploadOptions, type UploadResult, type UploadUrlResult, type UserRecord, ValidationError, createClient };