hydrousdb 3.0.2 → 3.5.0

package/dist/index.d.ts

@@ -1,67 +1,49 @@
+/**
+ * The server base URL — no trailing slash, no /api suffix.
+ * Routes in routes.ts already include /api, /api/analytics, /api/auth, /storage.
+ */
+declare const DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
 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>;
+    /**
+     * PUT directly to a signed GCS URL.
+     * Uses XHR in browsers for onprogress support; fetch in Node.
+     */
+    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_`). Required for auth routes. */
     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.
+     * Used for records and analytics routes.
      */
     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 value starts with `ssk_`.
+     * Key names are arbitrary labels you choose; pass the same label to `db.storage('label')`.
+     * Example: { avatars: 'ssk_…', documents: '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.
+     * Should NOT include /api — route paths are fully qualified in routes.ts.
      */
     baseUrl?: string;
 }
@@ -103,24 +85,26 @@ interface AuthResult {
 interface UpdateUserOptions {
     sessionId: string;
     userId: string;
-    data: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
+    /** Fields to update. Sent as `updates: {...}` to the server. */
+    updates: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
 }
 interface ChangePasswordOptions {
     sessionId: string;
     userId: string;
+    /** Sent to server as `oldPassword`. */
     currentPassword: string;
     newPassword: string;
 }
 interface ListUsersOptions {
     sessionId: string;
     limit?: number;
-    offset?: number;
+    /** URL-encoded cursor returned by the previous page. */
+    cursor?: string;
 }
 interface ListUsersResult {
     users: UserRecord[];
-    total: number;
-    limit: number;
-    offset: number;
+    hasMore: boolean;
+    nextCursor: string | null;
 }
 type RecordData = Record<string, unknown>;
 interface RecordResult {
@@ -131,7 +115,7 @@ interface RecordResult {
 }
 interface QueryFilter {
     field: string;
-    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'contains';
     value: string | number | boolean;
 }
 interface QueryOptions {
@@ -141,6 +125,10 @@ interface QueryOptions {
     offset?: number;
     orderBy?: string;
     order?: 'asc' | 'desc';
+    /**
+     * Pagination cursor — pass the `nextCursor` from the previous page.
+     * Maps to `?cursor=` on the server.
+     */
     startAfter?: string;
     startAt?: string;
     endAt?: string;
@@ -156,19 +144,36 @@ interface PatchRecordOptions {
     merge?: boolean;
 }
 interface RecordHistoryEntry {
-    id: string;
-    version: number;
-    createdAt: number;
-    data: RecordData;
+    generation: number | null;
+    savedAt: number | null;
+    savedBy: string | null;
+    sizeBytes: number | null;
+}
+/** Options for `records.create()`. */
+interface CreateRecordOptions {
+    /**
+     * Fields to index for server-side filtering.
+     * Only listed fields will be queryable via `query({ filters: [...] })`.
+     */
+    queryableFields?: string[];
+    /** User email for audit trails. */
+    userEmail?: string;
+    /**
+     * Custom record ID for upsert behaviour.
+     * Format: `YYMMDD-segment1__segment2` (e.g. `260307-user_alice__post_1`).
+     * If the ID already exists the record is updated in-place.
+     */
+    customRecordId?: string;
+}
+/** Options for `records.batchCreate()`. */
+interface BatchCreateOptions {
+    queryableFields?: string[];
+    userEmail?: string;
 }
 interface UploadOptions {
-    /** Set to true to make the file publicly accessible without authentication. */
     isPublic?: boolean;
-    /** Set to true to overwrite an existing file at the same path. */
     overwrite?: boolean;
-    /** MIME type of the file. Auto-detected if omitted. */
     mimeType?: string;
-    /** TTL in seconds for the signed upload URL (default 900 = 15 min). */
     expiresInSeconds?: number;
 }
 interface UploadResult {
@@ -195,6 +200,7 @@ interface ListOptions {
 interface FileEntry {
     name: string;
     path: string;
+    type?: 'file' | 'folder';
     size?: number;
     mimeType?: string;
     isPublic?: boolean;
@@ -243,14 +249,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 +278,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 +298,6 @@ interface AnalyticsQuery {
     order?: SortOrder;
     n?: number;
     metrics?: MetricDefinition[];
-    /** For crossBucket queries: list of bucket names to compare. */
     bucketKeys?: string[];
 }
 interface AnalyticsResult<T = unknown> {
@@ -337,54 +352,127 @@ interface CrossBucketRow {
 }
 
 /**
- * AuthClient — full user authentication for a single bucket.
- * Uses the `authKey` (`hk_auth_…`) sent via `X-Api-Key` header.
+ * AuthClient — user authentication for a project.
+ *
+ * All routes are under `/api/auth` (NOT `/api/auth/:bucketKey`).
+ * The server resolves which user bucket to use from the API key itself.
+ * Uses `X-Api-Key: <authKey>`.
  *
  * @example
  * ```ts
- * const db = createClient({ authKey: 'hk_auth_…', bucketSecurityKey: '…', storageKeys: { main: '…' } });
- * const auth = db.auth('my-app-users');
+ * const auth = db.auth();
  * const { user, session } = await auth.signup({ email: 'alice@example.com', password: 'hunter2' });
  * ```
  */
 declare class AuthClient {
     private readonly http;
     private readonly authKey;
-    private readonly basePath;
-    constructor(http: HttpClient, authKey: string, bucketKey: string);
+    constructor(http: HttpClient, authKey: string);
     private post;
     private get;
     private patch;
-    private delete;
+    /**
+     * Register a new user account.
+     *
+     * Server: POST /api/auth/signup
+     * Body: { email, password, fullName?, ...extraData }
+     */
     signup(options: SignupOptions): Promise<AuthResult>;
+    /**
+     * Sign in with email + password.
+     *
+     * Server: POST /api/auth/signin   (NOT /login)
+     * Body: { email, password }
+     */
     login(options: LoginOptions): Promise<AuthResult>;
-    logout({ sessionId }: {
+    /**
+     * Sign out — revoke a session (or all sessions with `allDevices: true`).
+     *
+     * Server: POST /api/auth/signout
+     * Body: { sessionId, allDevices? }
+     */
+    logout(options: {
         sessionId: string;
+        allDevices?: boolean;
     }): Promise<void>;
-    refreshSession({ refreshToken }: {
-        refreshToken: string;
-    }): Promise<Session>;
-    getUser({ userId }: {
-        userId: string;
-    }): Promise<UserRecord>;
+    /**
+     * Validate an existing session and retrieve the current user.
+     *
+     * Server: POST /api/auth/session/validate
+     * Body: { sessionId }
+     */
+    validateSession(sessionId: string): Promise<{
+        user: UserRecord;
+        session: {
+            sessionId: string;
+            expiresAt: number;
+        };
+    }>;
+    /**
+     * Rotate a refresh token to get a new session.
+     *
+     * Server: POST /api/auth/session/refresh
+     * Body: { refreshToken }
+     */
+    refreshSession(refreshToken: string): Promise<Session>;
+    /**
+     * Fetch a user by ID.
+     *
+     * Server: GET /api/auth/user?userId=:userId
+     */
+    getUser(userId: string): Promise<UserRecord>;
+    /**
+     * Update a user's profile fields.
+     * Regular users can only update themselves; admins can update any user.
+     *
+     * Server: PATCH /api/auth/user
+     * Body: { sessionId, userId, updates: { ...fields } }
+     */
     updateUser(options: UpdateUserOptions): Promise<UserRecord>;
-    deleteUser({ sessionId, userId }: {
-        sessionId: string;
-        userId: string;
-    }): Promise<void>;
+    /**
+     * Soft-delete a user account.
+     * Regular users can only delete themselves; admins can delete any user.
+     *
+     * Server: DELETE /api/auth/user?userId=:userId
+     * Body: { sessionId }
+     */
+    deleteUser(sessionId: string, userId: string): Promise<void>;
+    /**
+     * List all users (paginated). Admin only.
+     *
+     * Server: GET /api/auth/users?limit=&cursor=
+     * The sessionId is passed via the X-Session-Id header (GET body is unreliable).
+     */
     listUsers(options: ListUsersOptions): Promise<ListUsersResult>;
-    hardDeleteUser({ sessionId, userId }: {
-        sessionId: string;
-        userId: string;
-    }): Promise<void>;
-    bulkDeleteUsers({ sessionId, userIds }: {
+    /**
+     * Permanently delete a user (hard delete — cannot be undone).
+     * Admin only. Charged at 1 HC per deletion.
+     *
+     * Server: DELETE /api/auth/user/hard?userId=:userId
+     * Body: { sessionId }
+     */
+    hardDeleteUser(sessionId: string, userId: string): Promise<void>;
+    /**
+     * Delete multiple users at once (soft or hard). Admin only.
+     *
+     * Server: DELETE /api/auth/users/bulk
+     * Body: { userIds, hard?, sessionId }
+     */
+    bulkDeleteUsers(options: {
         sessionId: string;
         userIds: string[];
+        hard?: boolean;
     }): Promise<{
-        deleted: number;
-        failed: string[];
+        succeeded: number;
+        failed: number;
     }>;
-    lockAccount({ sessionId, userId, duration }: {
+    /**
+     * Lock a user account for a specified duration. Admin only.
+     *
+     * Server: POST /api/auth/account/lock
+     * Body: { sessionId, userId, duration? }  — duration in ms, default 15 min
+     */
+    lockAccount(options: {
         sessionId: string;
         userId: string;
         duration?: number;
@@ -392,103 +480,252 @@ declare class AuthClient {
         lockedUntil: number;
         unlockTime: string;
     }>;
-    unlockAccount({ sessionId, userId }: {
-        sessionId: string;
-        userId: string;
-    }): Promise<void>;
+    /**
+     * Unlock a locked user account. Admin only.
+     *
+     * Server: POST /api/auth/account/unlock
+     * Body: { sessionId, userId }
+     */
+    unlockAccount(sessionId: string, userId: string): Promise<void>;
+    /**
+     * Change a user's password. Requires both a valid session AND the old password.
+     *
+     * Server: POST /api/auth/password/change
+     * Body: { sessionId, userId, oldPassword, newPassword }
+     */
     changePassword(options: ChangePasswordOptions): Promise<void>;
-    requestPasswordReset({ email }: {
-        email: string;
-    }): Promise<void>;
-    confirmPasswordReset({ resetToken, newPassword }: {
-        resetToken: string;
-        newPassword: string;
-    }): Promise<void>;
-    requestEmailVerification({ userId }: {
-        userId: string;
-    }): Promise<void>;
-    confirmEmailVerification({ verifyToken }: {
-        verifyToken: string;
-    }): Promise<void>;
+    /**
+     * Request a password reset email.
+     * Always returns success regardless of whether the email exists (prevents enumeration).
+     *
+     * Server: POST /api/auth/password/reset/request
+     * Body: { email }
+     */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * Confirm a password reset using the token from the reset email.
+     *
+     * Server: POST /api/auth/password/reset/confirm
+     * Body: { resetToken, newPassword }
+     */
+    confirmPasswordReset(resetToken: string, newPassword: string): Promise<void>;
+    /**
+     * Request a verification email be sent to a user.
+     *
+     * Server: POST /api/auth/email/verify/request
+     * Body: { userId }
+     */
+    requestEmailVerification(userId: string): Promise<void>;
+    /**
+     * Confirm email ownership using the token from the verification email.
+     *
+     * Server: POST /api/auth/email/verify/confirm
+     * Body: { verifyToken }
+     */
+    confirmEmailVerification(verifyToken: string): Promise<void>;
+    private _buildAuthResult;
 }
 
 /**
- * RecordsClient — CRUD + query for a single bucket.
- * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
+ * RecordsClient — typed CRUD + batch + query for a single bucket.
+ *
+ * All requests use `X-Api-Key: <bucketSecurityKey>`.
+ * Routes: GET|POST|PATCH|DELETE /api/:bucketKey
  *
  * @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 basePath;
-    private readonly bucketKey_;
+    private readonly apiKey;
     constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
-    private get key();
-    create(data: T): Promise<T & RecordResult>;
+    /**
+     * Create a new record (auto-generated ID) or upsert by `customRecordId`.
+     *
+     * Server: POST /api/:bucketKey
+     * Body: { values, queryableFields?, userEmail?, customRecordId? }
+     * Returns 201 for new records, 200 for upserts.
+     *
+     * @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.
+     *
+     * Server: GET /api/:bucketKey?recordId=:id
+     */
     get(id: string): Promise<T & RecordResult>;
-    set(id: string, data: T): Promise<T & RecordResult>;
-    patch(id: string, data: Partial<T>, options?: PatchRecordOptions): Promise<T & RecordResult>;
+    /**
+     * Partially update an existing record (PATCH semantics).
+     * Supports write-filter sentinels: `{ __op: 'increment', delta: 1 }` etc.
+     *
+     * Server: PATCH /api/:bucketKey
+     * Body: { recordId, values, userEmail?, track_record_history? }
+     */
+    patch(id: string, data: Partial<T>, options?: PatchRecordOptions & {
+        userEmail?: string;
+        trackHistory?: boolean;
+    }): Promise<{
+        id: string;
+        updatedAt?: number;
+    }>;
+    /**
+     * Delete a record permanently.
+     *
+     * Server: DELETE /api/:bucketKey?recordId=:id
+     */
     delete(id: string): Promise<void>;
-    batchCreate(items: T[]): Promise<(T & RecordResult)[]>;
-    batchDelete(ids: string[]): Promise<{
-        deleted: number;
+    /**
+     * Check whether a record exists (HEAD request — very lightweight).
+     *
+     * Server: HEAD /api/:bucketKey?recordId=:id
+     * Returns true if the record exists, false if 404.
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Get a historical snapshot of a record at a specific generation.
+     *
+     * Server: GET /api/:bucketKey?recordId=:id&generation=:gen
+     */
+    getVersion(id: string, generation: string | number): Promise<T & RecordResult>;
+    /**
+     * Get the version history of a record.
+     *
+     * Server: GET /api/:bucketKey?recordId=:id&showHistory=true
+     */
+    getHistory(id: string): Promise<RecordHistoryEntry[]>;
+    /**
+     * Create up to 500 records in one request.
+     * Each record may include `_customRecordId` for upsert behaviour.
+     *
+     * Server: POST /api/:bucketKey/batch/insert
+     * Body: { records, queryableFields?, userEmail? }
+     *
+     * @example
+     * ```ts
+     * const results = await posts.batchCreate(
+     *   [{ title: 'A' }, { title: 'B' }],
+     *   { queryableFields: ['title'] },
+     * );
+     * ```
+     */
+    batchCreate(items: T[], options?: BatchCreateOptions): Promise<{
+        results: (T & RecordResult)[];
+        errors: unknown[];
+        successful: number;
+        failed: number;
+    }>;
+    /**
+     * Update up to 500 records in one request.
+     *
+     * Server: POST /api/:bucketKey/batch/update
+     * Body: { updates: [{ recordId, values }], userEmail? }
+     */
+    batchUpdate(updates: Array<{
+        recordId: string;
+        values: Partial<T>;
+    }>, userEmail?: string): Promise<{
+        successful: number;
         failed: string[];
     }>;
+    /**
+     * Delete up to 500 records in one request.
+     *
+     * Server: POST /api/:bucketKey/batch/delete
+     * Body: { recordIds, userEmail? }
+     */
+    batchDelete(ids: string[], userEmail?: string): Promise<{
+        successful: number;
+        failed: string[];
+    }>;
+    /**
+     * Query records with filters, sorting, and cursor-based pagination.
+     *
+     * Server: GET /api/:bucketKey?field=value&field[op]=value&limit=&sortBy=&sortOrder=&cursor=
+     *
+     * @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>>;
+    /**
+     * Retrieve all records matching options (no filter support — use `query()` for filters).
+     */
     getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
-    count(filters?: QueryOptions['filters']): Promise<number>;
-    getHistory(id: string): Promise<RecordHistoryEntry[]>;
-    restoreVersion(id: string, version: number): Promise<T & RecordResult>;
 }
 
 /**
- * AnalyticsClient — BigQuery-powered aggregations for a bucket.
- * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
+ * AnalyticsClient — BigQuery-powered aggregations for a single bucket.
+ *
+ * All methods POST a `queryType` body to `POST /api/analytics/:bucketKey`.
+ * The `dateRange` is passed as `{ start, end }` ms timestamps — the server
+ * converts them to ISO date strings internally.
+ * Uses `X-Api-Key: <bucketSecurityKey>`.
  *
  * @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 {
     private readonly http;
     private readonly bucketSecurityKey;
-    private readonly basePath;
+    private readonly bucketKey;
     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. records per status).
+     * `order` maps to `sortBy` on the wire (the server param name).
+     */
     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 +733,15 @@ 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 (BigQuery).
+     * Bypasses Firestore pagination — useful for large result sets.
+     */
     records<T extends RecordData = RecordData>(opts?: {
         filters?: AnalyticsFilter[];
         selectFields?: string[];
@@ -509,97 +751,96 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<(T & RecordResult)[]>;
+    /**
+     * Compute multiple aggregations in a single request.
+     * `metrics` must have valid `field` and `name` (used as BigQuery column aliases).
+     */
     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`.
+     * System buckets (`users`, `_sys_*`) are blocked server-side.
+     */
     crossBucket(opts: {
         bucketKeys: string[];
         field: string;
         aggregation?: Aggregation;
         dateRange?: DateRange;
     }): Promise<CrossBucketRow[]>;
+    /**
+     * Raw query — escape hatch when the typed helpers don't cover your 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`.
+ * Uses `X-Storage-Key: <ssk_…>` header — separate from auth and bucket keys.
+ * Files are scoped server-side to `hydrous-storage/{ownerId}/{userPath}`.
+ * You only ever deal with your own `userPath` — the server handles scoping.
+ *
+ * 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 storage = db.storage('avatars');
+ * const result  = await storage.upload(file, 'alice.jpg', { isPublic: true });
+ * console.log(result.publicUrl);
  * ```
  */
 declare class StorageManager {
     private readonly http;
     private readonly storageKey;
-    private readonly basePath;
     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.
+     * Upload a file in one step (server-buffered, up to 500 MB).
+     * For files >10 MB or when upload progress tracking is needed, use the
+     * signed URL flow: `getUploadUrl()` → `uploadToSignedUrl()` → `confirmUpload()`.
      *
-     * @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.
+     * Server: POST /storage/upload  (multipart/form-data)
      *
      * @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 string or JSON data directly as a file.
+     *
+     * Server: POST /storage/upload-raw
+     * Body: { path, content, mimeType?, isPublic?, overwrite? }
      *
      * @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 PUT URL for direct client-to-GCS upload.
+     *
+     * Server: POST /storage/upload-url
+     * Body: { path, mimeType, size, isPublic?, overwrite?, expiresIn? }
      *
      * @example
      * ```ts
-     * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
-     *   path: 'videos/intro.mp4',
-     *   mimeType: 'video/mp4',
-     *   size: file.size,
-     *   isPublic: true,
-     * });
-     *
-     * // Upload using XHR for progress tracking
-     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (pct) => {
-     *   console.log(`${pct}% uploaded`);
+     * const { uploadUrl, path: p } = await storage.getUploadUrl({
+     *   path: 'videos/intro.mp4', mimeType: 'video/mp4', size: file.size,
      * });
-     *
-     * // Step 3: confirm
-     * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
+     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => setProgress(pct));
+     * const result = await storage.confirmUpload({ path: p, mimeType: 'video/mp4' });
      * ```
      */
     getUploadUrl(opts: {
@@ -611,28 +852,15 @@ 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 the signed GCS URL.
+     * Supports progress tracking in browser environments via XHR.
      */
-    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.
+     * Step 3 — confirm a direct upload and register metadata server-side.
      *
-     * @example
-     * ```ts
-     * const result = await storage.confirmUpload({
-     *   path: 'videos/intro.mp4',
-     *   mimeType: 'video/mp4',
-     *   isPublic: true,
-     * });
-     * console.log(result.publicUrl);
-     * ```
+     * Server: POST /storage/confirm
+     * Body: { path, mimeType, isPublic? }
      */
     confirmUpload(opts: {
         path: string;
@@ -640,112 +868,79 @@ declare class StorageManager {
         isPublic?: boolean;
     }): Promise<UploadResult>;
     /**
-     * Get signed upload URLs for multiple files at once.
+     * Get signed upload URLs for up to 50 files at once.
      *
-     * @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 },
-     * ]);
-     *
-     * // 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 });
-     * }
-     * ```
+     * Server: POST /storage/batch-upload-urls
+     * Body: { files: [...], expiresIn? }
      */
     getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
     /**
      * Confirm multiple direct uploads at once.
+     *
+     * Server: POST /storage/batch-confirm
+     * Body: { files: [{ path, mimeType, isPublic? }] }
      */
     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));
-     * ```
+     * Server: GET /storage/download/:path  (requires X-Storage-Key)
      */
     download(path: string): Promise<ArrayBuffer>;
     /**
-     * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+     * Download up to 20 files at once. Returns base64-encoded content.
      *
-     * @example
-     * ```ts
-     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
-     * ```
+     * Server: POST /storage/batch-download
+     * Body: { paths, concurrency? }
      */
-    batchDownload(paths: string[]): Promise<Record<string, string>>;
+    batchDownload(paths: string[], concurrency?: number): Promise<BatchDownloadResult>;
     /**
      * List files and folders at a given path prefix.
      *
+     * Server: GET /storage/list?prefix=&limit=&cursor=
+     *
      * @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).
+     * Get file metadata: size, MIME type, visibility, URLs.
      *
-     * @example
-     * ```ts
-     * const meta = await storage.getMetadata('avatars/alice.jpg');
-     * console.log(meta.size, meta.isPublic, meta.publicUrl);
-     * ```
+     * Server: GET /storage/metadata/:path
      */
     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`.
+     * Can be shared externally — no X-Storage-Key required to access.
      *
-     * > **Note:** Downloads via signed URLs bypass the server, so download stats
-     * > are NOT tracked. Use `downloadUrl` for tracked downloads.
+     * Note: Downloads via signed URLs bypass the server — stats are NOT tracked.
      *
-     * @param path       Path to the file.
-     * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+     * Server: POST /storage/signed-url
+     * Body: { path, expiresIn? }
      *
-     * @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.
+     * Change a file's visibility between public and private.
      *
-     * @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
-     * ```
+     * Server: PATCH /storage/visibility
+     * Body: { path, isPublic }
      */
     setVisibility(path: string, isPublic: boolean): Promise<{
         path: string;
@@ -754,44 +949,33 @@ declare class StorageManager {
         downloadUrl: string | null;
     }>;
     /**
-     * Create a folder (a GCS prefix placeholder).
+     * Create a folder (empty GCS object used as a prefix marker).
      *
-     * @example
-     * ```ts
-     * await storage.createFolder('uploads/2025/');
-     * ```
+     * Server: POST /storage/folder
+     * Body: { path }
      */
     createFolder(path: string): Promise<{
         path: string;
     }>;
     /**
-     * Delete a single file.
+     * Permanently delete a file.
      *
-     * @example
-     * ```ts
-     * await storage.deleteFile('avatars/old-avatar.jpg');
-     * ```
+     * Server: DELETE /storage/file
+     * Body: { path }
      */
     deleteFile(path: string): Promise<void>;
     /**
-     * Delete a folder and all its contents recursively.
+     * Recursively delete a folder and all its contents.
      *
-     * @example
-     * ```ts
-     * await storage.deleteFolder('temp/');
-     * ```
+     * Server: DELETE /storage/folder
+     * Body: { path }
      */
     deleteFolder(path: string): Promise<void>;
     /**
-     * Move or rename a file.
+     * Move (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');
-     * ```
+     * Server: POST /storage/move
+     * Body: { from, to }
      */
     move(from: string, to: string): Promise<{
         from: string;
@@ -800,33 +984,23 @@ declare class StorageManager {
     /**
      * Copy a file to a new path.
      *
-     * @example
-     * ```ts
-     * await storage.copy('templates/base.html', 'sites/my-site/index.html');
-     * ```
+     * Server: POST /storage/copy
+     * Body: { from, to }
      */
     copy(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
     /**
-     * Get storage statistics for your key: total files, bytes, operation counts.
+     * Get usage statistics for this storage key.
      *
-     * @example
-     * ```ts
-     * const stats = await storage.getStats();
-     * console.log(`${stats.totalFiles} files, ${(stats.totalBytes / 1e6).toFixed(1)} MB`);
-     * ```
+     * Server: GET /storage/stats
      */
     getStats(): Promise<StorageStats>;
     /**
-     * Ping the storage service. No authentication required.
+     * Get server info (no auth required).
      *
-     * @example
-     * ```ts
-     * const info = await storage.info();
-     * // → { ok: true, storageRoot: 'hydrous-storage' }
-     * ```
+     * Server: GET /storage/info
      */
     info(): Promise<{
         ok: boolean;
@@ -835,190 +1009,159 @@ declare class StorageManager {
 }
 
 /**
- * ScopedStorage — a StorageManager pre-scoped to a specific folder prefix.
+ * ScopedStorage — a path-prefixed view over a StorageManager.
  *
- * All paths are automatically prepended with the scope, so you never
- * have to repeat the folder name.
+ * Every path you pass is automatically prefixed with the scope.
+ * 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;
 }
 
-/**
- * HydrousClient — the main entry point for the HydrousDB SDK.
- *
- * Each service uses its own dedicated key:
- * - `authKey`            (`hk_auth_…`)   → `db.auth('bucket')`
- * - `bucketSecurityKey`  (`hk_bucket_…`) → `db.records('bucket')` + `db.analytics('bucket')`
- * - `storageKeys`        (`ssk_…`)       → `db.storage('keyName')`
- *
- * @example
- * ```ts
- * import { createClient } from 'hydrousdb';
- *
- * const db = createClient({
- *   authKey:           'hk_auth_…',
- *   bucketSecurityKey: 'hk_bucket_…',
- *   storageKeys: {
- *     main:      'ssk_main_…',
- *     avatars:   'ssk_avatars_…',
- *     documents: 'ssk_docs_…',
- *   },
- * });
- *
- * // Records & Analytics — use bucketSecurityKey automatically
- * const posts     = db.records('blog-posts');
- * 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');
- * ```
- */
 declare class HydrousClient {
     private readonly http;
     private readonly authKey_;
     private readonly bucketSecurityKey_;
     private readonly storageKeys_;
     private readonly _recordsCache;
-    private readonly _authCache;
     private readonly _analyticsCache;
     private readonly _storageCache;
+    private _authClient?;
     constructor(config: HydrousConfig);
     /**
-     * Get a typed records client for the named bucket.
-     * Uses your `bucketSecurityKey` automatically.
+     * Get a typed RecordsClient for a bucket.
      *
      * @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 });
      * ```
      */
     records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
     /**
-     * Get an auth client for the named user bucket.
-     * Uses your `authKey` automatically.
+     * Get the AuthClient.
+     * Auth routes are NOT bucket-scoped in the URL — the bucket is determined
+     * server-side from the API key itself.
      *
      * @example
      * ```ts
-     * const auth = db.auth('app-users');
-     * const { user, session } = await auth.login({ email: '…', password: '…' });
+     * const { user, session } = await db.auth().signup({ email: 'alice@example.com', password: 'pw' });
      * ```
      */
-    auth(bucketKey: string): AuthClient;
+    auth(): AuthClient;
     /**
-     * Get an analytics client for the named bucket.
-     * Uses your `bucketSecurityKey` automatically.
+     * Get an AnalyticsClient for a bucket.
      *
      * @example
      * ```ts
-     * const analytics = db.analytics('orders');
-     * const { count } = await analytics.count();
+     * const { count } = await db.analytics('orders').count();
      * ```
      */
     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.
+     * Get a StorageManager for a named storage key.
+     * The name must match a key in the `storageKeys` config object.
      *
-     * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
+     * Attach `.scope('prefix/')` to get a path-prefixed ScopedStorage.
      *
      * @example
      * ```ts
-     * const avatars   = db.storage('avatars');
-     * const documents = db.storage('documents');
-     *
-     * // Upload to avatars bucket
-     * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
+     * const avatars = db.storage('avatars');
+     * const result  = await avatars.upload(file, 'alice.jpg', { isPublic: true });
      *
-     * // Scope to a sub-folder
-     * const userDocs = db.storage('documents').scope(`users/${userId}`);
-     * await userDocs.upload(pdfBuffer, 'contract.pdf');
+     * // Scoped:
+     * const userFiles = db.storage('documents').scope(`users/${userId}/`);
+     * await userFiles.upload(pdf, 'contract.pdf');
      * ```
      */
     storage(keyName: string): StorageManager & {
@@ -1026,33 +1169,135 @@ declare class HydrousClient {
     };
 }
 /**
- * Create a new HydrousDB client.
+ * Create a HydrousDB client.
  *
  * @example
  * ```ts
- * import { createClient } from 'hydrousdb';
+ * import { createClient } from 'hydrous-sdk';
  *
  * 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!,
- *   },
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys:       { avatars: 'ssk_…' },
  * });
  * ```
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
+/**
+ * routes.ts — Single source of truth for every API path in the HydrousDB SDK.
+ *
+ * Base URL: https://db-api-82687684612.us-central1.run.app
+ *
+ * Mount points (from server.js):
+ *   /api          → records router   (X-Api-Key: bucketSecurityKey)
+ *   /api/analytics → analytics router (X-Api-Key: bucketSecurityKey)
+ *   /api/auth      → auth router      (X-Api-Key: authKey)
+ *   /storage       → storage router   (X-Storage-Key: ssk_…)
+ *
+ * ⚠️  Keys MUST be sent in headers — NEVER in URLs or query strings.
+ *     Records + Analytics: X-Api-Key  (or Authorization: Bearer …)
+ *     Storage:             X-Storage-Key (or Authorization: Bearer …)
+ */
+declare const RECORDS: {
+    /** GET|POST|PATCH|DELETE|HEAD /api/:bucketKey */
+    readonly bucket: (bucketKey: string) => string;
+    /** POST /api/:bucketKey/batch/insert */
+    readonly batchInsert: (bucketKey: string) => string;
+    /** POST /api/:bucketKey/batch/update */
+    readonly batchUpdate: (bucketKey: string) => string;
+    /** POST /api/:bucketKey/batch/delete */
+    readonly batchDelete: (bucketKey: string) => string;
+};
+declare const ANALYTICS: {
+    /** POST /api/analytics/:bucketKey */
+    readonly query: (bucketKey: string) => string;
+};
+declare const AUTH: {
+    /** POST /api/auth/signup   body: { email, password, fullName?, ...extra } */
+    readonly signup: "/api/auth/signup";
+    /** POST /api/auth/signin   body: { email, password } */
+    readonly signin: "/api/auth/signin";
+    /** POST /api/auth/signout  body: { sessionId, allDevices? } */
+    readonly signout: "/api/auth/signout";
+    /** POST /api/auth/session/validate  body: { sessionId } */
+    readonly sessionValidate: "/api/auth/session/validate";
+    /** POST /api/auth/session/refresh   body: { refreshToken } */
+    readonly sessionRefresh: "/api/auth/session/refresh";
+    /** GET  /api/auth/user?userId=... */
+    readonly getUser: "/api/auth/user";
+    /** GET  /api/auth/users?limit=&cursor= */
+    readonly listUsers: "/api/auth/users";
+    /** PATCH /api/auth/user  body: { sessionId, userId, updates: {...} } */
+    readonly updateUser: "/api/auth/user";
+    /** DELETE /api/auth/user?userId=...  body: { sessionId } */
+    readonly deleteUser: "/api/auth/user";
+    /** DELETE /api/auth/user/hard?userId=...  body: { sessionId } */
+    readonly hardDeleteUser: "/api/auth/user/hard";
+    /** DELETE /api/auth/users/bulk  body: { userIds, hard?, sessionId } */
+    readonly bulkDeleteUsers: "/api/auth/users/bulk";
+    /** POST /api/auth/password/change  body: { sessionId, userId, oldPassword, newPassword } */
+    readonly passwordChange: "/api/auth/password/change";
+    /** POST /api/auth/password/reset/request  body: { email } */
+    readonly passwordResetRequest: "/api/auth/password/reset/request";
+    /** POST /api/auth/password/reset/confirm  body: { resetToken, newPassword } */
+    readonly passwordResetConfirm: "/api/auth/password/reset/confirm";
+    /** POST /api/auth/email/verify/request  body: { userId } */
+    readonly emailVerifyRequest: "/api/auth/email/verify/request";
+    /** POST /api/auth/email/verify/confirm  body: { verifyToken } */
+    readonly emailVerifyConfirm: "/api/auth/email/verify/confirm";
+    /** POST /api/auth/account/lock    body: { sessionId, userId, duration? } */
+    readonly accountLock: "/api/auth/account/lock";
+    /** POST /api/auth/account/unlock  body: { sessionId, userId } */
+    readonly accountUnlock: "/api/auth/account/unlock";
+};
+declare const STORAGE: {
+    /** GET /storage/info  — no auth required */
+    readonly info: "/storage/info";
+    /** GET /storage/public/:fullScopedPath  — no auth required */
+    readonly publicFile: (fullScopedPath: string) => string;
+    /** POST /storage/upload-url  body: { path, mimeType, size, isPublic?, overwrite?, expiresIn? } */
+    readonly uploadUrl: "/storage/upload-url";
+    /** POST /storage/batch-upload-urls  body: { files: [...], expiresIn? } */
+    readonly batchUploadUrls: "/storage/batch-upload-urls";
+    /** POST /storage/confirm  body: { path, mimeType, isPublic? } */
+    readonly confirm: "/storage/confirm";
+    /** POST /storage/batch-confirm  body: { files: [...] } */
+    readonly batchConfirm: "/storage/batch-confirm";
+    /** POST /storage/upload  multipart/form-data: file, path, mimeType, isPublic, overwrite */
+    readonly upload: "/storage/upload";
+    /** POST /storage/upload-raw  body: { path, content, mimeType?, isPublic?, overwrite? } */
+    readonly uploadRaw: "/storage/upload-raw";
+    /** GET /storage/list?prefix=&limit=&cursor= */
+    readonly list: "/storage/list";
+    /** GET /storage/download/:path  — requires X-Storage-Key */
+    readonly download: (filePath: string) => string;
+    /** POST /storage/batch-download  body: { paths: [...], concurrency? } */
+    readonly batchDownload: "/storage/batch-download";
+    /** GET /storage/metadata/:path */
+    readonly metadata: (filePath: string) => string;
+    /** POST /storage/signed-url  body: { path, expiresIn? } */
+    readonly signedUrl: "/storage/signed-url";
+    /** PATCH /storage/visibility  body: { path, isPublic } */
+    readonly visibility: "/storage/visibility";
+    /** POST /storage/folder  body: { path } */
+    readonly folder: "/storage/folder";
+    /** DELETE /storage/file  body: { path } */
+    readonly file: "/storage/file";
+    /** DELETE /storage/folder  body: { path } */
+    readonly folderDelete: "/storage/folder";
+    /** POST /storage/move  body: { from, to } */
+    readonly move: "/storage/move";
+    /** POST /storage/copy  body: { from, to } */
+    readonly copy: "/storage/copy";
+    /** GET /storage/stats */
+    readonly stats: "/storage/stats";
+};
+
 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 +1322,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 { ANALYTICS, AUTH, 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, DEFAULT_BASE_URL, type DateRange, type DistributionRow, type FieldStats, type FieldTimeSeriesRow, type FileEntry, type FileMetadata, type Granularity, HttpClient, 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, RECORDS, type RecordData, RecordError, type RecordHistoryEntry, type RecordResult, RecordsClient, STORAGE, 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 };