hydrousdb 3.2.0 → 3.5.0

package/dist/index.d.cts

@@ -1,3 +1,8 @@
+/**
+ * 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: string;
     body?: unknown;
@@ -14,21 +19,32 @@ declare class HttpClient {
     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.
+     * 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>;
 }
 
 type StorageKeys = Record<string, string>;
 interface HydrousConfig {
-    /** Auth service key (starts with `hk_auth_`). */
+    /** Auth service key (starts with `hk_auth_`). Required for auth routes. */
     authKey: string;
-    /** Bucket security key (starts with `hk_bucket_`). Used for records + analytics. */
+    /**
+     * Bucket security key (starts with `hk_bucket_`).
+     * Used for records and analytics routes.
+     */
     bucketSecurityKey: string;
-    /** Named storage keys (each starts with `ssk_`). */
+    /**
+     * 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. */
+    /**
+     * 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;
 }
 interface SignupOptions {
@@ -69,20 +85,20 @@ interface AuthResult {
 interface UpdateUserOptions {
     sessionId: string;
     userId: string;
-    /** Fields to update — nested under `updates` when sent to the server. */
+    /** Fields to update. Sent as `updates: {...}` to the server. */
     updates: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
 }
 interface ChangePasswordOptions {
     sessionId: string;
     userId: string;
-    /** Maps to `oldPassword` on the server. */
+    /** Sent to server as `oldPassword`. */
     currentPassword: string;
     newPassword: string;
 }
 interface ListUsersOptions {
     sessionId: string;
     limit?: number;
-    /** Cursor for the next page (URL-encoded value returned by the previous call). */
+    /** URL-encoded cursor returned by the previous page. */
     cursor?: string;
 }
 interface ListUsersResult {
@@ -99,7 +115,7 @@ interface RecordResult {
 }
 interface QueryFilter {
     field: string;
-    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'contains';
     value: string | number | boolean;
 }
 interface QueryOptions {
@@ -109,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;
@@ -124,41 +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 creating a record — includes queryable fields for filtering. */
+/** Options for `records.create()`. */
 interface CreateRecordOptions {
     /**
-     * Fields that should be indexed for server-side filtering.
-     * Only fields listed here will be queryable via `query({ filters: [...] })`.
+     * Fields to index for server-side filtering.
+     * Only listed fields will be queryable via `query({ filters: [...] })`.
      */
     queryableFields?: string[];
-    /** Email of the user performing the action (for audit trails). */
+    /** User email 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.
+     * 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 batch-creating records. */
+/** Options for `records.batchCreate()`. */
 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 {
-    /** Make the file publicly accessible without authentication. */
     isPublic?: boolean;
-    /** Overwrite an existing file at the same path. */
     overwrite?: boolean;
-    /** 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;
 }
 interface UploadResult {
@@ -337,59 +352,112 @@ 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 `/auth/:bucketKey/` — the bucketKey is the user bucket
- * name you passed when calling `db.auth('bucketKey')`.
+ * 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_…', … });
- * const auth = db.auth('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>;
+    /**
+     * 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>;
-    validateSession({ sessionId }: {
-        sessionId: string;
-    }): Promise<{
+    /**
+     * 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;
         };
     }>;
-    getUser({ userId }: {
-        userId: string;
-    }): Promise<UserRecord>;
+    /**
+     * 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>;
+    /**
+     * 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[];
@@ -398,6 +466,12 @@ declare class AuthClient {
         succeeded: number;
         failed: number;
     }>;
+    /**
+     * 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;
@@ -406,29 +480,57 @@ 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 — typed CRUD + query + batch 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
@@ -441,14 +543,13 @@ declare class RecordsClient<T extends RecordData = RecordData> {
     private readonly http;
     private readonly bucketKey;
     private readonly apiKey;
-    private readonly basePath;
     constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
     /**
-     * Create a new record.
+     * Create a new record (auto-generated ID) or upsert by `customRecordId`.
      *
-     * @param data    The record fields to store.
-     * @param options Optional: queryableFields (for server-side filtering),
-     *                userEmail (audit trail), customRecordId (upsert by ID).
+     * Server: POST /api/:bucketKey
+     * Body: { values, queryableFields?, userEmail?, customRecordId? }
+     * Returns 201 for new records, 200 for upserts.
      *
      * @example
      * ```ts
@@ -461,44 +562,97 @@ declare class RecordsClient<T extends RecordData = RecordData> {
     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>;
     /**
-     * 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.
+     * 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): Promise<T & RecordResult>;
+    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>;
     /**
-     * Create multiple records in one request (max 500).
-     * Each record can include a `_customRecordId` field for upsert behaviour.
+     * 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 created = await posts.batchCreate(
+     * const results = await posts.batchCreate(
      *   [{ title: 'A' }, { title: 'B' }],
-     *   { queryableFields: ['title'], userEmail: 'alice@example.com' },
+     *   { queryableFields: ['title'] },
      * );
      * ```
      */
-    batchCreate(items: T[], options?: BatchCreateOptions): Promise<(T & RecordResult)[]>;
+    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 multiple records in one request (max 500).
+     * Delete up to 500 records in one request.
+     *
+     * Server: POST /api/:bucketKey/batch/delete
+     * Body: { recordIds, userEmail? }
      */
-    batchDelete(ids: string[]): Promise<{
-        deleted: number;
+    batchDelete(ids: string[], userEmail?: string): Promise<{
+        successful: number;
         failed: string[];
     }>;
     /**
-     * Query records with optional filters, sorting, and pagination.
+     * Query records with filters, sorting, and cursor-based pagination.
+     *
+     * Server: GET /api/:bucketKey?field=value&field[op]=value&limit=&sortBy=&sortOrder=&cursor=
      *
      * @example
      * ```ts
@@ -512,30 +666,18 @@ declare class RecordsClient<T extends RecordData = RecordData> {
      */
     query(options?: QueryOptions): Promise<QueryResult<T>>;
     /**
-     * Get all records matching the given options (no filter support — use `query()` for filters).
+     * Retrieve all records matching 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 single bucket.
- * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
  *
- * All methods POST a `queryType` body to `POST /analytics/:bucketKey`.
+ * 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
@@ -547,14 +689,17 @@ declare class RecordsClient<T extends RecordData = RecordData> {
 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. how many records per status). */
+    /**
+     * 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;
@@ -593,7 +738,10 @@ declare class AnalyticsClient {
         field: string;
         dateRange?: DateRange;
     }): Promise<FieldStats>;
-    /** Fetch filtered records via the analytics engine (bypasses Firestore pagination). */
+    /**
+     * 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[];
@@ -603,7 +751,10 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<(T & RecordResult)[]>;
-    /** Compute multiple aggregations in a single request. */
+    /**
+     * 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;
@@ -614,7 +765,8 @@ declare class AnalyticsClient {
     }): Promise<StorageStatsResult>;
     /**
      * Compare a metric across multiple buckets in one query.
-     * The caller's key must have read access to every bucket in `bucketKeys`.
+     * 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[];
@@ -623,34 +775,39 @@ declare class AnalyticsClient {
         dateRange?: DateRange;
     }): Promise<CrossBucketRow[]>;
     /**
-     * Raw query — use this when none of the typed helpers cover your use case.
+     * 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.
+ *
+ * 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 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;
-    readonly basePath = "/storage";
     constructor(http: HttpClient, storageKey: string);
     private get authHeaders();
     /**
-     * Upload a file to storage in one step (server-buffered, up to 500 MB).
-     * For files >10 MB or when upload progress is needed, use `getUploadUrl()`.
+     * 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()`.
+     *
+     * Server: POST /storage/upload  (multipart/form-data)
      *
      * @example
      * ```ts
@@ -660,7 +817,10 @@ declare class StorageManager {
      */
     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
@@ -669,19 +829,18 @@ declare class StorageManager {
      */
     uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
     /**
-     * Step 1 — get a signed GCS URL to upload directly from the client.
-     * Supports upload progress via `uploadToSignedUrl()`.
+     * 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,
+     * const { uploadUrl, path: p } = await storage.getUploadUrl({
+     *   path: 'videos/intro.mp4', mimeType: 'video/mp4', size: file.size,
      * });
-     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => console.log(pct + '%'));
-     * 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: {
@@ -693,12 +852,15 @@ declare class StorageManager {
         expiresInSeconds?: number;
     }): Promise<UploadUrlResult>;
     /**
-     * Step 2 — upload data directly to a signed GCS URL.
-     * Supports progress tracking in browser environments.
+     * 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, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
     /**
-     * Step 3 — confirm a direct upload and register metadata on the server.
+     * Step 3 — confirm a direct upload and register metadata server-side.
+     *
+     * Server: POST /storage/confirm
+     * Body: { path, mimeType, isPublic? }
      */
     confirmUpload(opts: {
         path: string;
@@ -706,25 +868,17 @@ declare class StorageManager {
         isPublic?: boolean;
     }): Promise<UploadResult>;
     /**
-     * Get signed upload URLs for multiple files at once (max 50).
-     * Server returns `{ succeeded, failed }` — only succeeded items have URLs.
+     * Get signed upload URLs for up to 50 files at once.
      *
-     * @example
-     * ```ts
-     * const { files } = await storage.getBatchUploadUrls([
-     *   { path: 'images/a.jpg', mimeType: 'image/jpeg', size: 204800 },
-     *   { path: 'images/b.jpg', mimeType: 'image/jpeg', size: 153600 },
-     * ]);
-     * 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.
-     * Returns both succeeded and failed results.
+     *
+     * Server: POST /storage/batch-confirm
+     * Body: { files: [{ path, mimeType, isPublic? }] }
      */
     batchConfirmUploads(items: Array<{
         path: string;
@@ -740,25 +894,21 @@ declare class StorageManager {
     /**
      * Download a private file as an ArrayBuffer.
      * For public files, use the `publicUrl` directly — no SDK needed.
+     *
+     * Server: GET /storage/download/:path  (requires X-Storage-Key)
      */
     download(path: string): Promise<ArrayBuffer>;
     /**
-     * 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.
+     * Download up to 20 files at once. Returns base64-encoded content.
      *
-     * @example
-     * ```ts
-     * const { succeeded, failed } = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
-     * for (const f of succeeded) {
-     *   const bytes = Buffer.from(f.content, 'base64');
-     * }
-     * ```
+     * Server: POST /storage/batch-download
+     * Body: { paths, concurrency? }
      */
-    batchDownload(paths: string[]): Promise<BatchDownloadResult>;
+    batchDownload(paths: string[], concurrency?: number): Promise<BatchDownloadResult>;
     /**
      * List files and folders at a given path prefix.
-     * Returns separate `files` and `folders` arrays for easy consumption.
+     *
+     * Server: GET /storage/list?prefix=&limit=&cursor=
      *
      * @example
      * ```ts
@@ -768,21 +918,29 @@ declare class StorageManager {
      */
     list(opts?: ListOptions): Promise<ListResult>;
     /**
-     * Get metadata for a file: size, MIME type, visibility, URLs.
+     * Get file metadata: size, MIME type, visibility, URLs.
+     *
+     * Server: GET /storage/metadata/:path
      */
     getMetadata(path: string): Promise<FileMetadata>;
     /**
      * Generate a time-limited download URL for a private file.
-     * 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 — download stats are NOT tracked.
+     * Note: Downloads via signed URLs bypass the server — stats are NOT tracked.
+     *
+     * Server: POST /storage/signed-url
+     * Body: { path, expiresIn? }
      *
      * @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.
+     *
+     * Server: PATCH /storage/visibility
+     * Body: { path, isPublic }
      */
     setVisibility(path: string, isPublic: boolean): Promise<{
         path: string;
@@ -790,20 +948,60 @@ declare class StorageManager {
         publicUrl: string | null;
         downloadUrl: string | null;
     }>;
+    /**
+     * Create a folder (empty GCS object used as a prefix marker).
+     *
+     * Server: POST /storage/folder
+     * Body: { path }
+     */
     createFolder(path: string): Promise<{
         path: string;
     }>;
+    /**
+     * Permanently delete a file.
+     *
+     * Server: DELETE /storage/file
+     * Body: { path }
+     */
     deleteFile(path: string): Promise<void>;
+    /**
+     * Recursively delete a folder and all its contents.
+     *
+     * Server: DELETE /storage/folder
+     * Body: { path }
+     */
     deleteFolder(path: string): Promise<void>;
+    /**
+     * Move (rename) a file.
+     *
+     * Server: POST /storage/move
+     * Body: { from, to }
+     */
     move(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
+    /**
+     * Copy a file to a new path.
+     *
+     * Server: POST /storage/copy
+     * Body: { from, to }
+     */
     copy(from: string, to: string): Promise<{
         from: string;
         to: string;
     }>;
+    /**
+     * Get usage statistics for this storage key.
+     *
+     * Server: GET /storage/stats
+     */
     getStats(): Promise<StorageStats>;
+    /**
+     * Get server info (no auth required).
+     *
+     * Server: GET /storage/info
+     */
     info(): Promise<{
         ok: boolean;
         storageRoot: string;
@@ -812,8 +1010,8 @@ declare class StorageManager {
 
 /**
  * ScopedStorage — a path-prefixed view over a StorageManager.
- * All paths you pass are automatically prefixed with the scope.
  *
+ * Every path you pass is automatically prefixed with the scope.
  * Obtain via `db.storage('keyName').scope('prefix/')`.
  *
  * @example
@@ -823,7 +1021,7 @@ declare class StorageManager {
  * // Uploads to: users/{userId}/contract.pdf
  * await userDocs.upload(pdfBuffer, 'contract.pdf');
  *
- * // Lists:      users/{userId}/
+ * // Lists: users/{userId}/
  * const { files } = await userDocs.list();
  * ```
  */
@@ -863,7 +1061,8 @@ declare class ScopedStorage {
     download(path: string): Promise<ArrayBuffer>;
     batchDownload(paths: string[]): Promise<BatchDownloadResult>;
     /**
-     * List files within this scope. The `prefix` option is relative to the scope root.
+     * List files within this scope.
+     * The `prefix` option is relative to the scope root.
      *
      * @example
      * ```ts
@@ -900,7 +1099,7 @@ declare class ScopedStorage {
      *
      * @example
      * ```ts
-     * const user    = storage.scope('users/alice/');
+     * const user     = storage.scope('users/alice/');
      * const userDocs = user.scope('docs/');
      * // Effective prefix: users/alice/docs/
      * ```
@@ -908,92 +1107,61 @@ declare class ScopedStorage {
     scope(subPrefix: string): ScopedStorage;
 }
 
-/**
- * HydrousClient — the main entry point for the HydrousDB SDK.
- *
- * 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:           process.env.HYDROUS_AUTH_KEY!,
- *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
- *   storageKeys: {
- *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
- *     documents: process.env.HYDROUS_STORAGE_DOCS!,
- *   },
- * });
- *
- * const posts    = db.records('blog-posts');
- * const auth     = db.auth('app-users');
- * const analytics = db.analytics('orders');
- * const avatars  = db.storage('avatars');
- * ```
- */
 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.
+     * 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 },
-     *   { queryableFields: ['published'] },
-     * );
+     * 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.
+     * 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.
+     * 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 defined in `storageKeys` when calling `createClient`.
+     * Get a StorageManager for a named storage key.
+     * The name must match a key in the `storageKeys` config object.
      *
-     * Attach `.scope(prefix)` to namespace all operations under a path prefix.
+     * Attach `.scope('prefix/')` to get a path-prefixed ScopedStorage.
      *
      * @example
      * ```ts
-     * const avatars  = db.storage('avatars');
-     * const userDocs = db.storage('documents').scope(`users/${userId}/`);
+     * const avatars = db.storage('avatars');
+     * const result  = await avatars.upload(file, 'alice.jpg', { isPublic: true });
      *
-     * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-     * 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 & {
@@ -1001,21 +1169,131 @@ 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! },
+ *   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 {
     readonly code: string;
     readonly status?: number;
@@ -1044,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 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 };
+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 };