hydrousdb 2.0.3 → 3.0.0

package/dist/index.d.ts

@@ -1,180 +1,188 @@
-/**
- * Named storage keys.
- * Create as many as you need in the HydrousDB dashboard and give each one a
- * meaningful name — you'll reference it by name when calling storage methods.
- *
- * @example
- * {
- *   main:      'ssk_main_…',
- *   avatars:   'ssk_avatars_…',
- *   documents: 'ssk_docs_…',
- * }
- */
-type StorageKeys = Record<string, string>;
-interface HydrousConfig {
-    /** Your HydrousDB project base URL */
-    url: string;
-    /** Auth service key — used for all auth.* operations */
-    authKey: string;
-    /** Bucket security key — used for records.* and analytics.* operations */
-    bucketSecurityKey: string;
-    /**
-     * Storage keys object.  Each property name is a label you choose; each
-     * value is a storage key (ssk_…) from your dashboard.
-     * You can have as many as you need.
-     */
-    storageKeys: StorageKeys;
-    /** Optional global request timeout in milliseconds (default: 30 000) */
-    timeout?: number;
-}
-interface HydrousResponse<T = unknown> {
-    data: T | null;
-    error: HydrousError | null;
-}
-interface HydrousError {
-    message: string;
-    code: string;
-    status?: number;
-}
-type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'nin' | 'is' | 'not';
-interface Filter {
-    field: string;
-    operator: FilterOperator;
-    value: unknown;
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+    rawBody?: string | FormData | Uint8Array<ArrayBuffer>;
+    contentType?: string;
 }
-interface QueryOptions {
-    where?: Filter | Filter[];
-    orderBy?: {
-        field: string;
-        direction?: 'asc' | 'desc';
-    };
-    limit?: number;
-    offset?: number;
-    select?: string[];
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly securityKey;
+    constructor(baseUrl: string, securityKey: string);
+    request<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T = unknown>(path: 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>;
 }
-interface RecordResponse<T = Record<string, unknown>> {
-    data: T[];
-    count: number;
-    error: HydrousError | null;
+
+interface HydrousConfig {
+    /**
+     * Your project's Security Key (starts with `sk_`).
+     * Obtain this from your dashboard at https://hydrousdb.com/dashboard.
+     * This is your most important credential — keep it secret.
+     */
+    securityKey: string;
+    /**
+     * Override the API base URL. Defaults to the official HydrousDB endpoint.
+     * You almost never need to set this.
+     */
+    baseUrl?: string;
+}
+interface SignupOptions {
+    email: string;
+    password: string;
+    fullName?: string;
+    [key: string]: unknown;
 }
-interface SingleRecordResponse<T = Record<string, unknown>> {
-    data: T | null;
-    error: HydrousError | null;
+interface LoginOptions {
+    email: string;
+    password: string;
 }
-interface AuthUser {
+interface UserRecord {
     id: string;
     email: string;
-    createdAt: string;
-    updatedAt: string;
+    fullName?: string | null;
+    emailVerified: boolean;
+    accountStatus: 'active' | 'locked' | 'suspended';
+    role: 'user' | 'admin';
+    createdAt: number;
+    updatedAt: number;
     metadata?: Record<string, unknown>;
+    [key: string]: unknown;
 }
-interface AuthSession {
-    accessToken: string;
-    refreshToken: string;
+interface Session {
+    sessionId: string;
+    userId: string;
+    bucketId: string;
+    createdAt: number;
     expiresAt: number;
-    user: AuthUser;
+    refreshToken: string;
+    refreshExpiresAt: number;
 }
-interface SignUpOptions {
-    email: string;
-    password: string;
-    metadata?: Record<string, unknown>;
+interface AuthResult {
+    user: UserRecord;
+    session: Session;
 }
-interface SignInOptions {
-    email: string;
-    password: string;
+interface UpdateUserOptions {
+    sessionId: string;
+    userId: string;
+    data: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
+}
+interface ChangePasswordOptions {
+    sessionId: string;
+    userId: string;
+    currentPassword: string;
+    newPassword: string;
 }
-interface TrackEventOptions {
-    event: string;
-    properties?: Record<string, unknown>;
-    userId?: string;
-    sessionId?: string;
-    timestamp?: number;
-}
-interface AnalyticsQueryOptions {
-    event?: string;
-    from?: string;
-    to?: string;
+interface ListUsersOptions {
+    sessionId: string;
     limit?: number;
-    groupBy?: string;
+    offset?: number;
 }
-interface AnalyticsEvent {
-    id: string;
-    event: string;
-    properties: Record<string, unknown>;
-    userId?: string;
-    sessionId?: string;
-    timestamp: number;
-}
-type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
-interface UploadProgress {
-    /** 0-based file index (always 0 for single uploads) */
-    index: number;
-    /** Total files in the operation */
-    total: number;
-    /** Destination path in the bucket */
-    path: string;
-    /** Current lifecycle stage */
-    stage: UploadStage;
-    bytesUploaded: number;
-    totalBytes: number;
-    /** 0 – 100 */
-    percent: number;
-    /** Upload speed in bytes/sec; null until the first tick */
-    bytesPerSecond: number | null;
-    /** Estimated seconds remaining; null until speed is known */
-    eta: number | null;
-    result?: UploadResult;
-    error?: string;
-    code?: string;
-}
-interface DownloadProgress {
-    index: number;
+interface ListUsersResult {
+    users: UserRecord[];
     total: number;
-    path: string;
-    status: 'pending' | 'success' | 'error';
-    size?: number;
+    limit: number;
+    offset: number;
+}
+type RecordData = Record<string, unknown>;
+interface RecordResult {
+    id: string;
+    createdAt?: number;
+    updatedAt?: number;
+    [key: string]: unknown;
+}
+interface QueryFilter {
+    field: string;
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    value: string | number | boolean;
+}
+interface QueryOptions {
+    filters?: QueryFilter[];
+    fields?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+    startAfter?: string;
+    startAt?: string;
+    endAt?: string;
+    dateRange?: DateRange;
+}
+interface QueryResult<T = RecordData> {
+    records: (T & RecordResult)[];
+    total?: number;
+    hasMore?: boolean;
+    nextCursor?: string;
+}
+interface PatchRecordOptions {
+    merge?: boolean;
+}
+interface RecordHistoryEntry {
+    id: string;
+    version: number;
+    createdAt: number;
+    data: RecordData;
+}
+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;
-    error?: string;
+    /** TTL in seconds for the signed upload URL (default 900 = 15 min). */
+    expiresInSeconds?: number;
 }
 interface UploadResult {
     path: string;
-    compressed: boolean;
-    originalSize: number;
-    storedSize: number;
-    spaceSaved: number;
     mimeType: string;
+    size: number;
+    isPublic: boolean;
+    publicUrl: string | null;
+    downloadUrl: string | null;
 }
-interface FileMetadata {
+interface UploadUrlResult {
+    uploadUrl: string;
     path: string;
-    name: string;
-    size: number | null;
-    originalSize: number | null;
-    mimeType: string | null;
-    isCompressed: boolean;
-    md5Hash: string | null;
-    updatedAt: string | null;
-    createdAt: string | null;
-}
-interface StorageItem {
+    mimeType: string;
+    expiresAt: string;
+    expiresIn: number;
+}
+interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+    recursive?: boolean;
+}
+interface FileEntry {
     name: string;
     path: string;
-    type: 'file' | 'folder';
-    size?: number | null;
-    storedSize?: number | null;
-    mimeType?: string | null;
-    isCompressed?: boolean;
-    updatedAt?: string | null;
-    createdAt?: string | null;
-    md5Hash?: string | null;
+    size?: number;
+    mimeType?: string;
+    isPublic?: boolean;
+    publicUrl?: string | null;
+    downloadUrl?: string | null;
+    updatedAt?: string;
 }
 interface ListResult {
-    items: StorageItem[];
-    pagination: {
-        limit: number;
-        count: number;
-        hasNextPage: boolean;
-        nextCursor: string | null;
-    };
+    files: FileEntry[];
+    folders: string[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+interface FileMetadata {
+    path: string;
+    size: number;
+    mimeType: string;
+    isPublic: boolean;
+    publicUrl: string | null;
+    downloadUrl: string | null;
+    createdAt?: string;
+    updatedAt?: string;
 }
 interface SignedUrlResult {
     signedUrl: string;
@@ -182,373 +190,1351 @@ interface SignedUrlResult {
     expiresIn: number;
     path: string;
 }
-interface BatchUploadResult {
-    succeeded: UploadResult[];
-    failed: Array<{
-        path: string;
-        error: string;
-        code: string;
-    }>;
+interface StorageStats {
+    totalFiles: number;
+    totalBytes: number;
+    uploadCount: number;
+    downloadCount: number;
+    deleteCount: number;
 }
-interface BatchDownloadFile {
+interface BatchUploadItem {
     path: string;
-    content: ArrayBuffer;
     mimeType: string;
     size: number;
+    isPublic?: boolean;
+    overwrite?: boolean;
 }
-interface StorageStats {
-    totalFiles: number;
-    totalSizeBytes: number;
-    totalOriginalSizeBytes: number;
-    spaceSavedBytes: number;
-    uploadsCount: number;
-    downloadsCount: number;
-    deletesCount: number;
-    creditsUsedUpload: number;
-    creditsUsedDownload: number;
-    creditsTotalUsed: number;
-    bytesDelivered: number;
-    compressionRatio: string;
+interface BatchUploadUrlResult {
+    files: Array<UploadUrlResult & {
+        index: number;
+    }>;
 }
-interface UploadOptions {
-    /** Destination path in the bucket (defaults to the file's original name) */
-    path?: string;
-    /** Replace the file if it already exists (default: false) */
-    overwrite?: boolean;
-    /**
-     * Called on every progress tick.
-     * Use this to drive progress bars, speed displays, and ETAs.
-     */
-    onProgress?: (progress: UploadProgress) => void;
+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 BatchUploadOptions {
-    /** Folder prefix prepended to every filename */
-    prefix?: string;
-    /** Per-file paths (same order as the `files` array; takes priority over prefix) */
-    paths?: string[];
-    overwrite?: boolean;
-    /** Max simultaneous server-side uploads (1–10, default 5) */
-    concurrency?: number;
-    /** Called for every progress tick on every file */
-    onProgress?: (progress: UploadProgress) => void;
+interface AnalyticsFilter {
+    field: string;
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    value: string | number | boolean;
 }
-interface BatchDownloadOptions {
-    concurrency?: number;
-    onProgress?: (progress: DownloadProgress) => void;
-    /**
-     * Browser only — automatically triggers a Save dialog for each file as it
-     * arrives (default: false)
-     */
-    autoSave?: 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 ListOptions {
-    /** Folder prefix to list (empty = bucket root) */
-    prefix?: string;
+interface AnalyticsQuery {
+    queryType: QueryType;
+    dateRange?: DateRange;
+    field?: string;
+    groupBy?: string;
+    labelField?: string;
+    aggregation?: Aggregation;
+    granularity?: Granularity;
+    filters?: AnalyticsFilter[];
+    selectFields?: string[];
     limit?: number;
-    cursor?: string;
+    offset?: number;
+    orderBy?: string;
+    order?: SortOrder;
+    n?: number;
+    metrics?: MetricDefinition[];
+    /** For crossBucket queries: list of bucket names to compare. */
+    bucketKeys?: string[];
 }
-interface SignedUrlOptions {
-    /** How long the URL stays valid in seconds (default: 3600) */
-    expiresIn?: number;
+interface AnalyticsResult<T = unknown> {
+    queryType: QueryType;
+    data: T;
 }
-
-declare class AuthClient {
-    private readonly baseUrl;
-    private readonly headers;
-    private session;
-    constructor(config: HydrousConfig);
-    /** Create a new user account */
-    signUp(options: SignUpOptions): Promise<HydrousResponse<AuthSession>>;
-    /** Sign in with email and password */
-    signIn(options: SignInOptions): Promise<HydrousResponse<AuthSession>>;
-    /** Sign out and invalidate the current session */
-    signOut(): Promise<HydrousResponse<void>>;
-    /** Get the currently authenticated user */
-    getUser(): Promise<HydrousResponse<AuthUser>>;
-    /** Refresh the access token using the stored refresh token */
-    refreshSession(): Promise<HydrousResponse<AuthSession>>;
-    /** Return the current in-memory session (may be null) */
-    getSession(): AuthSession | null;
-    private _sessionHeader;
+interface CountResult {
+    count: number;
 }
-
-declare class RecordsClient {
-    private readonly baseUrl;
-    private readonly headers;
-    constructor(config: HydrousConfig);
-    /** Query records from a collection */
-    select<T = Record<string, unknown>>(collection: string, options?: QueryOptions): Promise<RecordResponse<T>>;
-    /** Fetch a single record by ID */
-    get<T = Record<string, unknown>>(collection: string, id: string): Promise<SingleRecordResponse<T>>;
-    /** Insert one or more records */
-    insert<T = Record<string, unknown>>(collection: string, payload: Partial<T> | Partial<T>[]): Promise<RecordResponse<T>>;
-    /** Update a record by ID */
-    update<T = Record<string, unknown>>(collection: string, id: string, payload: Partial<T>): Promise<SingleRecordResponse<T>>;
-    /** Delete a record by ID */
-    delete(collection: string, id: string): Promise<SingleRecordResponse<void>>;
+interface DistributionRow {
+    value: string | number;
+    count: number;
 }
-
-declare class AnalyticsClient {
-    private readonly baseUrl;
-    private readonly headers;
-    constructor(config: HydrousConfig);
-    /** Track a single analytics event */
-    track(options: TrackEventOptions): Promise<HydrousResponse<void>>;
-    /** Track many events in one request */
-    trackBatch(events: TrackEventOptions[]): Promise<HydrousResponse<void>>;
-    /** Query recorded analytics events */
-    query(options?: AnalyticsQueryOptions): Promise<RecordResponse<AnalyticsEvent>>;
+interface SumRow {
+    group?: string | number;
+    sum: number;
+}
+interface TimeSeriesRow {
+    date: string;
+    count: number;
+}
+interface FieldTimeSeriesRow {
+    date: string;
+    value: number;
+}
+interface TopNRow {
+    value: string | number;
+    label?: string;
+    count: number;
+}
+interface FieldStats {
+    min: number;
+    max: number;
+    avg: number;
+    sum: number;
+    count: number;
+    stddev?: number;
+}
+interface MultiMetricResult {
+    [metricName: string]: number;
+}
+interface StorageStatsResult {
+    totalRecords: number;
+    totalBytes: number;
+    avgBytes: number;
+    minBytes: number;
+    maxBytes: number;
+}
+interface CrossBucketRow {
+    bucket: string;
+    value: number;
 }
 
 /**
- * A storage client that is already bound to a specific storage key.
- * You get one of these by calling  `db.storage('keyName')`.
+ * AuthClient — full user authentication for a single bucket.
+ *
+ * Every method maps directly to a route in the server's `auth.js` router.
+ * The bucket key is the name of your user bucket (e.g. "users" or "customers").
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ securityKey: 'sk_...' });
+ * const auth = db.auth('my-app-users');
  *
- * None of the methods on this class require you to pass a bucket key —
- * it's already baked in.
+ * const { user, session } = await auth.signup({
+ *   email: 'alice@example.com',
+ *   password: 'hunter2',
+ *   fullName: 'Alice',
+ * });
+ * ```
  */
-declare class ScopedStorageClient {
-    private readonly base;
-    private readonly key;
-    readonly keyName: string;
-    constructor(baseUrl: string, keyName: string, bucketKey: string);
+declare class AuthClient {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketKey: string);
+    /**
+     * Register a new user in this bucket.
+     *
+     * @example
+     * ```ts
+     * const { user, session } = await auth.signup({
+     *   email: 'alice@example.com',
+     *   password: 'hunter2',
+     *   fullName: 'Alice Wonderland',
+     *   // Any extra fields are stored on the user record:
+     *   plan: 'pro',
+     * });
+     * ```
+     */
+    signup(options: SignupOptions): Promise<AuthResult>;
+    /**
+     * Authenticate an existing user and create a session.
+     * Sessions are valid for 24 hours; use `refreshSession` to extend.
+     *
+     * @example
+     * ```ts
+     * const { user, session } = await auth.login({
+     *   email: 'alice@example.com',
+     *   password: 'hunter2',
+     * });
+     * // Store session.sessionId safely — you'll need it for other calls.
+     * ```
+     */
+    login(options: LoginOptions): Promise<AuthResult>;
     /**
-     * Upload a single file.
+     * Invalidate a session (sign out).
      *
-     * Supply `onProgress` to receive live upload ticks including bytes
-     * transferred, speed (bytes/sec), ETA, and lifecycle stage.
+     * @example
+     * ```ts
+     * await auth.logout({ sessionId: session.sessionId });
+     * ```
+     */
+    logout({ sessionId }: {
+        sessionId: string;
+    }): Promise<void>;
+    /**
+     * Extend a session using its refresh token.
+     * Returns a new session object.
      *
-     * **Stage sequence:**
-     * `pending → compressing → uploading → done | error`
+     * @example
+     * ```ts
+     * const newSession = await auth.refreshSession({ refreshToken: session.refreshToken });
+     * ```
+     */
+    refreshSession({ refreshToken }: {
+        refreshToken: string;
+    }): Promise<Session>;
+    /**
+     * Fetch a user by their ID.
      *
-     * In browsers the progress is tracked at the network level via XHR, so
-     * `percent` reflects actual bytes leaving the device.  `done` only fires
-     * after the server confirms the write to cloud storage, so 100% is real.
+     * @example
+     * ```ts
+     * const user = await auth.getUser({ userId: 'usr_abc123' });
+     * ```
+     */
+    getUser({ userId }: {
+        userId: string;
+    }): Promise<UserRecord>;
+    /**
+     * Update fields on a user record. Requires a valid session.
      *
      * @example
-     * const { data, error } = await db.storage('avatars').upload(file, {
-     *   path:      'users/alice.jpg',
-     *   overwrite: true,
-     *   onProgress: (p) => {
-     *     setProgress(p.percent);              // e.g. drive a <progress> bar
-     *     setSpeed(`${p.bytesPerSecond} B/s`);
-     *     setEta(`${p.eta}s remaining`);
-     *   },
+     * ```ts
+     * const updated = await auth.updateUser({
+     *   sessionId: session.sessionId,
+     *   userId: user.id,
+     *   data: { fullName: 'Alice Smith', plan: 'enterprise' },
      * });
+     * ```
      */
-    upload(file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    updateUser(options: UpdateUserOptions): Promise<UserRecord>;
     /**
-     * Upload raw text or JSON content directly — no File object needed.
+     * Soft-delete a user. The record is marked deleted but not removed from storage.
+     * Requires a valid session (the user can delete themselves, or an admin can delete any user).
      *
      * @example
-     * // Save a JSON config
-     * await db.storage('configs').uploadText(
-     *   'settings/app.json',
-     *   JSON.stringify({ theme: 'dark' }),
-     *   { mimeType: 'application/json' }
-     * );
+     * ```ts
+     * await auth.deleteUser({ sessionId: session.sessionId, userId: user.id });
+     * ```
      */
-    uploadText(path: string, content: string, options?: {
-        mimeType?: string;
-        overwrite?: boolean;
-        onProgress?: UploadOptions['onProgress'];
-    }): Promise<HydrousResponse<UploadResult>>;
+    deleteUser({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    /**
+     * List all users in the bucket. **Admin session required.**
+     *
+     * @example
+     * ```ts
+     * const { users, total } = await auth.listUsers({
+     *   sessionId: adminSession.sessionId,
+     *   limit: 50,
+     *   offset: 0,
+     * });
+     * ```
+     */
+    listUsers(options: ListUsersOptions): Promise<ListUsersResult>;
     /**
-     * Upload multiple files in one request.
+     * Permanently hard-delete a user and all their data. **Admin session required.**
+     * This action is irreversible.
      *
-     * `onProgress` fires per file — use `p.index` to identify which file.
-     * All files receive a `pending` event upfront so you can render progress
-     * bars immediately before any data is sent.
+     * @example
+     * ```ts
+     * await auth.hardDeleteUser({ sessionId: adminSession.sessionId, userId: user.id });
+     * ```
+     */
+    hardDeleteUser({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    /**
+     * Bulk delete multiple users. **Admin session required.**
      *
      * @example
-     * await db.storage('documents').batchUpload(files, {
-     *   prefix:     'reports/2024/',
-     *   onProgress: (p) => updateBar(p.index, p.percent),
+     * ```ts
+     * const result = await auth.bulkDeleteUsers({
+     *   sessionId: adminSession.sessionId,
+     *   userIds: ['usr_a', 'usr_b'],
      * });
+     * ```
      */
-    batchUpload(files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    bulkDeleteUsers({ sessionId, userIds, }: {
+        sessionId: string;
+        userIds: string[];
+    }): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
     /**
-     * Download a single file and return its content as an `ArrayBuffer`.
+     * Lock a user account, preventing login. **Admin session required.**
+     *
+     * @param options.duration Lock duration in milliseconds. Defaults to 15 minutes.
      *
      * @example
-     * const { data } = await db.storage('avatars').download('users/alice.jpg');
-     * const blob = new Blob([data!]);
-     * img.src = URL.createObjectURL(blob);
+     * ```ts
+     * await auth.lockAccount({
+     *   sessionId: adminSession.sessionId,
+     *   userId: user.id,
+     *   duration: 60 * 60 * 1000, // 1 hour
+     * });
+     * ```
      */
-    download(filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    lockAccount({ sessionId, userId, duration, }: {
+        sessionId: string;
+        userId: string;
+        duration?: number;
+    }): Promise<{
+        lockedUntil: number;
+        unlockTime: string;
+    }>;
     /**
-     * Download multiple files in one request.
+     * Unlock a previously locked user account. **Admin session required.**
      *
-     * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
+     * @example
+     * ```ts
+     * await auth.unlockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+     * ```
+     */
+    unlockAccount({ sessionId, userId, }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    /**
+     * Change a user's password. The user must supply their current password.
      *
      * @example
-     * const { data } = await db.storage('reports').batchDownload(
-     *   ['jan.pdf', 'feb.pdf'],
-     *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
-     * );
+     * ```ts
+     * await auth.changePassword({
+     *   sessionId: session.sessionId,
+     *   userId: user.id,
+     *   currentPassword: 'hunter2',
+     *   newPassword: 'correcthorsebatterystaple',
+     * });
+     * ```
      */
-    batchDownload(filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    changePassword(options: ChangePasswordOptions): Promise<void>;
     /**
-     * List files and folders (paginated).
+     * Request a password reset email for a user.
+     * Always returns success to prevent user enumeration.
      *
      * @example
-     * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
-     * for (const item of data!.items) {
-     *   console.log(item.type, item.path, item.size);
-     * }
+     * ```ts
+     * await auth.requestPasswordReset({ email: 'alice@example.com' });
+     * ```
      */
-    list(options?: ListOptions): Promise<HydrousResponse<ListResult>>;
+    requestPasswordReset({ email }: {
+        email: string;
+    }): Promise<void>;
     /**
-     * Get metadata for a file (size, MIME type, compression, etc.)
+     * Complete a password reset using the token from the reset email.
      *
      * @example
-     * const { data: meta } = await db.storage('docs').metadata('report.pdf');
-     * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
+     * ```ts
+     * await auth.confirmPasswordReset({
+     *   resetToken: 'tok_from_email',
+     *   newPassword: 'correcthorsebatterystaple',
+     * });
+     * ```
      */
-    metadata(filePath: string): Promise<HydrousResponse<FileMetadata>>;
-    /** Delete a single file */
-    deleteFile(filePath: string): Promise<HydrousResponse<void>>;
-    /** Recursively delete a folder and all its contents */
-    deleteFolder(folderPath: string): Promise<HydrousResponse<void>>;
-    /** Create an empty folder */
-    createFolder(folderPath: string): Promise<HydrousResponse<void>>;
-    /** Move (rename) a file */
-    move(fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
-    /** Copy a file (original is kept) */
-    copy(fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    confirmPasswordReset({ resetToken, newPassword, }: {
+        resetToken: string;
+        newPassword: string;
+    }): Promise<void>;
     /**
-     * Generate a time-limited public URL for a private file.
+     * Send (or resend) an email verification message to a user.
      *
      * @example
-     * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
-     * console.log(data!.signedUrl); // share this
+     * ```ts
+     * await auth.requestEmailVerification({ userId: user.id });
+     * ```
      */
-    signedUrl(filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    requestEmailVerification({ userId }: {
+        userId: string;
+    }): Promise<void>;
     /**
-     * Get usage and billing stats for this storage key.
+     * Confirm an email address using the token from the verification email.
      *
      * @example
-     * const { data } = await db.storage('main').stats();
-     * console.log(data!.totalFiles, data!.totalSizeBytes);
+     * ```ts
+     * await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
+     * ```
      */
-    stats(): Promise<HydrousResponse<StorageStats>>;
+    confirmEmailVerification({ verifyToken }: {
+        verifyToken: string;
+    }): Promise<void>;
 }
 
-interface CallableStorage {
-    /** Get a scoped storage client by key name */
-    (keyName: string): ScopedStorageClient;
-    /** Same as calling db.storage(keyName) — more explicit */
-    use(keyName: string): ScopedStorageClient;
-    /** Return names of all configured storage keys */
-    keyNames(): string[];
-}
 /**
- * The HydrousDB root client.
+ * RecordsClient — create, read, update, delete, and query records in a bucket.
  *
- * Create once and reuse across your app:
+ * A bucket is simply a named collection of JSON records. You create buckets
+ * from your HydrousDB dashboard. Each record is a JSON object with any fields
+ * you want; HydrousDB automatically adds `id`, `createdAt`, and `updatedAt`.
  *
+ * @example
  * ```ts
- * import { createClient } from 'hydrousdb';
+ * const db = createClient({ securityKey: 'sk_...' });
+ * const posts = db.records('blog-posts');
  *
- * const db = createClient({
- *   url:               'https://api.myapp.hydrous.app',
- *   authKey:           'hk_auth_…',
- *   bucketSecurityKey: 'hk_bucket_…',
- *   storageKeys: {
- *     main:      'ssk_main_…',
- *     avatars:   'ssk_avatars_…',
- *     documents: 'ssk_docs_…',
- *   },
+ * // Create a record
+ * const post = await posts.create({ title: 'Hello World', status: 'draft' });
+ *
+ * // Query records
+ * const { records } = await posts.query({
+ *   filters: [{ field: 'status', op: '==', value: 'published' }],
+ *   limit: 20,
  * });
  * ```
  */
-declare class HydrousClient {
-    /** Auth — sign up, sign in, sign out, session management */
-    readonly auth: AuthClient;
-    /** Records — insert, select, update, delete structured data */
-    readonly records: RecordsClient;
-    /** Analytics — track events and query history */
-    readonly analytics: AnalyticsClient;
+declare class RecordsClient<T extends RecordData = RecordData> {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketKey: string);
     /**
-     * Storage — call with the name of the key you want.
+     * Create a new record.
      *
+     * @example
      * ```ts
-     * db.storage('avatars').upload(file, { path: 'user.jpg' })
-     * db.storage('documents').list({ prefix: 'invoices/' })
-     * db.storage('main').stats()
+     * const user = await records.create({
+     *   name: 'Alice',
+     *   email: 'alice@example.com',
+     *   score: 100,
+     * });
+     * console.log(user.id); // "rec_xxxxxxxx"
      * ```
      */
-    readonly storage: CallableStorage;
-    constructor(config: HydrousConfig);
-}
-
-/**
- * StorageManager is the object exposed as `db.storage`.
- *
- * Call `.use(keyName)` — or use the shorthand `db.storage('keyName')` which
- * the main HydrousClient wires up as a Proxy — to get a scoped storage client
- * bound to that key.
- *
- * ```ts
- * db.storage('main').upload(file)
- * db.storage('avatars').list()
- * db.storage('documents').download('report.pdf')
- * ```
- */
-declare class StorageManager {
-    private readonly baseUrl;
-    private readonly _keys;
-    private readonly cache;
-    constructor(config: HydrousConfig);
+    create(data: T): Promise<T & RecordResult>;
+    /**
+     * Fetch a single record by ID.
+     *
+     * @example
+     * ```ts
+     * const post = await records.get('rec_abc123');
+     * ```
+     */
+    get(id: string): Promise<T & RecordResult>;
     /**
-     * Get a storage client scoped to a named key.
+     * Overwrite a record entirely (full replace).
      *
-     * @param keyName - Must match a property you declared in `storageKeys`
+     * @example
+     * ```ts
+     * const updated = await records.set('rec_abc123', {
+     *   name: 'Alice Updated',
+     *   email: 'alice2@example.com',
+     * });
+     * ```
+     */
+    set(id: string, data: T): Promise<T & RecordResult>;
+    /**
+     * Partially update a record (merge by default).
      *
      * @example
-     * const avatarStore   = db.storage('avatars');
-     * const documentStore = db.storage('documents');
+     * ```ts
+     * // Merge: only the provided fields are updated
+     * const updated = await records.patch('rec_abc123', { score: 200 });
      *
-     * await avatarStore.upload(file, { path: 'users/alice.jpg' });
-     * const list = await documentStore.list({ prefix: 'invoices/' });
+     * // Replace: equivalent to set()
+     * const replaced = await records.patch('rec_abc123', { score: 200 }, { merge: false });
+     * ```
      */
-    use(keyName: string): ScopedStorageClient;
-    /** Return the names of all configured storage keys */
-    keyNames(): string[];
-}
-
-declare const eq: (field: string, value: unknown) => Filter;
-declare const neq: (field: string, value: unknown) => Filter;
-declare const gt: (field: string, value: unknown) => Filter;
-declare const lt: (field: string, value: unknown) => Filter;
-declare const gte: (field: string, value: unknown) => Filter;
-declare const lte: (field: string, value: unknown) => Filter;
-declare const inArray: (field: string, value: unknown[]) => Filter;
-
-declare class HydrousDBError extends Error {
-    readonly code: string;
-    readonly status: number | undefined;
-    constructor(message: string, code?: string, status?: number);
-}
-declare function isHydrousError(err: unknown): err is HydrousDBError;
-
-/**
- * Create a HydrousDB client.
- *
- * @example
- * import { createClient } from 'hydrousdb';
- *
- * const db = createClient({
- *   url:               'https://api.myapp.hydrous.app',
- *   authKey:           'hk_auth_…',
- *   bucketSecurityKey: 'hk_bucket_…',
- *   storageKeys: {
- *     main:      'ssk_main_…',
- *     avatars:   'ssk_avatars_…',
- *     documents: 'ssk_docs_…',
- *   },
- * });
- */
-declare function createClient(config: HydrousConfig): HydrousClient;
+    patch(id: string, data: Partial<T>, options?: PatchRecordOptions): Promise<T & RecordResult>;
+    /**
+     * Delete a record permanently.
+     *
+     * @example
+     * ```ts
+     * await records.delete('rec_abc123');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Create multiple records in one request.
+     *
+     * @example
+     * ```ts
+     * const created = await records.batchCreate([
+     *   { name: 'Alice', score: 100 },
+     *   { name: 'Bob',   score: 200 },
+     * ]);
+     * ```
+     */
+    batchCreate(items: T[]): Promise<(T & RecordResult)[]>;
+    /**
+     * Delete multiple records by ID in one request.
+     *
+     * @example
+     * ```ts
+     * await records.batchDelete(['rec_a', 'rec_b', 'rec_c']);
+     * ```
+     */
+    batchDelete(ids: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    /**
+     * Query records with optional filters, sorting, and pagination.
+     *
+     * @example
+     * ```ts
+     * // Simple query
+     * const { records } = await posts.query({ limit: 10 });
+     *
+     * // Filtered query with cursor pagination
+     * const page1 = await posts.query({
+     *   filters: [
+     *     { field: 'status',    op: '==', value: 'published' },
+     *     { field: 'views',     op: '>',  value: 1000 },
+     *   ],
+     *   orderBy: 'createdAt',
+     *   order: 'desc',
+     *   limit: 20,
+     * });
+     *
+     * const page2 = await posts.query({
+     *   filters: [{ field: 'status', op: '==', value: 'published' }],
+     *   limit: 20,
+     *   startAfter: page1.nextCursor,
+     * });
+     * ```
+     */
+    query(options?: QueryOptions): Promise<QueryResult<T>>;
+    /**
+     * Convenience alias: get all records up to `limit` (default 100).
+     *
+     * @example
+     * ```ts
+     * const allPosts = await posts.getAll({ limit: 500 });
+     * ```
+     */
+    getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
+    /**
+     * Count records matching optional filters.
+     *
+     * @example
+     * ```ts
+     * const total = await posts.count([{ field: 'status', op: '==', value: 'published' }]);
+     * ```
+     */
+    count(filters?: QueryOptions['filters']): Promise<number>;
+    /**
+     * Retrieve the full version history of a record.
+     * Each write creates a new version stored in GCS.
+     *
+     * @example
+     * ```ts
+     * const history = await records.getHistory('rec_abc123');
+     * console.log(history[0].data); // latest version
+     * ```
+     */
+    getHistory(id: string): Promise<RecordHistoryEntry[]>;
+    /**
+     * Restore a record to a specific historical version.
+     *
+     * @example
+     * ```ts
+     * const history = await records.getHistory('rec_abc123');
+     * const restored = await records.restoreVersion('rec_abc123', history[2].version);
+     * ```
+     */
+    restoreVersion(id: string, version: number): Promise<T & RecordResult>;
+}
+
+/**
+ * AnalyticsClient — run powerful aggregation and time-series queries against
+ * your bucket data using BigQuery under the hood.
+ *
+ * All query types accept an optional `dateRange` to filter by time.
+ * The security key is sent automatically — you never pass it manually.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ securityKey: 'sk_...' });
+ * const analytics = db.analytics('orders');
+ *
+ * // How many orders in the last 30 days?
+ * const { count } = await analytics.count({
+ *   dateRange: { start: Date.now() - 30 * 24 * 60 * 60 * 1000, end: Date.now() },
+ * });
+ * ```
+ */
+declare class AnalyticsClient {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketKey: string);
+    /** Internal dispatcher — all queries POST to the same endpoint. */
+    private run;
+    /**
+     * Count the total number of records in the bucket, with optional date filter.
+     *
+     * @example
+     * ```ts
+     * const { count } = await analytics.count();
+     * // → { count: 4821 }
+     *
+     * // Count only this month's records
+     * const { count } = await analytics.count({
+     *   dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
+     * });
+     * ```
+     */
+    count(opts?: {
+        dateRange?: DateRange;
+    }): Promise<CountResult>;
+    /**
+     * Count how many records have each unique value for a given field.
+     * Great for pie charts and bar charts.
+     *
+     * @example
+     * ```ts
+     * const rows = await analytics.distribution({
+     *   field: 'status',
+     *   limit: 10,
+     *   order: 'desc',
+     * });
+     * // → [{ value: 'completed', count: 312 }, { value: 'pending', count: 88 }, ...]
+     * ```
+     */
+    distribution(opts: {
+        field: string;
+        limit?: number;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<DistributionRow[]>;
+    /**
+     * Sum a numeric field, optionally grouped by another field.
+     *
+     * @example
+     * ```ts
+     * // Total revenue
+     * const rows = await analytics.sum({ field: 'amount' });
+     * // → [{ sum: 198432.50 }]
+     *
+     * // Revenue by country
+     * const rows = await analytics.sum({ field: 'amount', groupBy: 'country', limit: 10 });
+     * // → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
+     * ```
+     */
+    sum(opts: {
+        field: string;
+        groupBy?: string;
+        limit?: number;
+        dateRange?: DateRange;
+    }): Promise<SumRow[]>;
+    /**
+     * Count records created over time, grouped by a time granularity.
+     * Perfect for line charts and activity graphs.
+     *
+     * @example
+     * ```ts
+     * const rows = await analytics.timeSeries({
+     *   granularity: 'day',
+     *   dateRange: { start: Date.now() - 7 * 86400000, end: Date.now() },
+     * });
+     * // → [{ date: '2025-06-01', count: 42 }, { date: '2025-06-02', count: 67 }, ...]
+     * ```
+     */
+    timeSeries(opts?: {
+        granularity?: Granularity;
+        dateRange?: DateRange;
+    }): Promise<TimeSeriesRow[]>;
+    /**
+     * Aggregate a numeric field over time (e.g. daily revenue, hourly signups).
+     *
+     * @example
+     * ```ts
+     * const rows = await analytics.fieldTimeSeries({
+     *   field: 'amount',
+     *   aggregation: 'sum',
+     *   granularity: 'week',
+     * });
+     * // → [{ date: '2025-W22', value: 14230.50 }, ...]
+     * ```
+     */
+    fieldTimeSeries(opts: {
+        field: string;
+        aggregation?: Aggregation;
+        granularity?: Granularity;
+        dateRange?: DateRange;
+    }): Promise<FieldTimeSeriesRow[]>;
+    /**
+     * Get the top N values by frequency for a field.
+     * Optionally pair with a `labelField` for human-readable labels.
+     *
+     * @example
+     * ```ts
+     * // Top 5 most purchased products
+     * const rows = await analytics.topN({
+     *   field: 'productId',
+     *   labelField: 'productName',
+     *   n: 5,
+     * });
+     * // → [{ value: 'prod_123', label: 'Widget Pro', count: 892 }, ...]
+     * ```
+     */
+    topN(opts: {
+        field: string;
+        n?: number;
+        labelField?: string;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<TopNRow[]>;
+    /**
+     * Get statistical summary (min, max, avg, sum, count, stddev) for a numeric field.
+     *
+     * @example
+     * ```ts
+     * const stats = await analytics.stats({ field: 'orderValue' });
+     * // → { min: 4.99, max: 9999.99, avg: 87.23, sum: 420948.27, count: 4823, stddev: 143.2 }
+     * ```
+     */
+    stats(opts: {
+        field: string;
+        dateRange?: DateRange;
+    }): Promise<FieldStats>;
+    /**
+     * Query raw records with filters, field selection, and pagination.
+     * This is the analytics version of `records.query()` but powered by BigQuery.
+     *
+     * @example
+     * ```ts
+     * const { records } = await analytics.records({
+     *   filters: [{ field: 'status', op: '==', value: 'refunded' }],
+     *   selectFields: ['orderId', 'amount', 'createdAt'],
+     *   limit: 50,
+     *   orderBy: 'amount',
+     *   order: 'desc',
+     * });
+     * ```
+     */
+    records<T extends RecordData = RecordData>(opts?: {
+        filters?: AnalyticsFilter[];
+        selectFields?: string[];
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<(T & RecordResult)[]>;
+    /**
+     * Calculate multiple aggregations in a single query.
+     * Ideal for dashboards that need several numbers at once.
+     *
+     * @example
+     * ```ts
+     * const result = await analytics.multiMetric({
+     *   metrics: [
+     *     { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
+     *     { field: 'amount',   name: 'avgOrderValue', aggregation: 'avg' },
+     *     { field: 'userId',   name: 'uniqueCustomers', aggregation: 'count' },
+     *   ],
+     * });
+     * // → { totalRevenue: 198432.50, avgOrderValue: 87.23, uniqueCustomers: 2275 }
+     * ```
+     */
+    multiMetric(opts: {
+        metrics: MetricDefinition[];
+        dateRange?: DateRange;
+    }): Promise<MultiMetricResult>;
+    /**
+     * Get storage statistics for this bucket: record counts, byte sizes.
+     *
+     * @example
+     * ```ts
+     * const stats = await analytics.storageStats();
+     * // → { totalRecords: 4821, totalBytes: 48293820, avgBytes: 10015, ... }
+     * ```
+     */
+    storageStats(opts?: {
+        dateRange?: DateRange;
+    }): Promise<StorageStatsResult>;
+    /**
+     * Compare the same field aggregation across multiple buckets in one query.
+     * Your security key must have read access to ALL listed buckets.
+     *
+     * @example
+     * ```ts
+     * const rows = await analytics.crossBucket({
+     *   bucketKeys: ['orders-us', 'orders-eu', 'orders-apac'],
+     *   field: 'amount',
+     *   aggregation: 'sum',
+     * });
+     * // → [
+     * //   { bucket: 'orders-us',   value: 120000 },
+     * //   { bucket: 'orders-eu',   value: 45000 },
+     * //   { bucket: 'orders-apac', value: 33000 },
+     * // ]
+     * ```
+     */
+    crossBucket(opts: {
+        bucketKeys: string[];
+        field: string;
+        aggregation?: Aggregation;
+        dateRange?: DateRange;
+    }): Promise<CrossBucketRow[]>;
+    /**
+     * Send a raw analytics query object. Use this when you need full control
+     * over the query shape or want to use a queryType not covered by the helpers.
+     *
+     * @example
+     * ```ts
+     * const result = await analytics.query({
+     *   queryType: 'topN',
+     *   field: 'category',
+     *   n: 3,
+     *   order: 'asc',
+     * });
+     * ```
+     */
+    query<T = unknown>(query: AnalyticsQuery): Promise<AnalyticsResult<T>>;
+}
+
+/**
+ * StorageManager — upload, download, list, move, copy, and delete files.
+ *
+ * Authentication is handled automatically via the X-Storage-Key header.
+ * Files are scoped to your owner ID — you can never access another owner's files.
+ *
+ * **Recommended upload flow** (for progress tracking and large files):
+ * 1. Call `getUploadUrl()` to get a signed PUT URL.
+ * 2. Upload directly to GCS using XHR (supports progress events).
+ * 3. Call `confirmUpload()` to finalize metadata.
+ *
+ * **Simple upload** (small files, no progress needed):
+ * - Call `upload()` — it handles everything in one call.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ securityKey: 'sk_...' });
+ *
+ * // Simple upload
+ * const file = await db.storage.upload(fileBlob, 'avatars/alice.jpg', { isPublic: true });
+ * console.log(file.publicUrl); // CDN URL, usable anywhere
+ * ```
+ */
+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.
+     *
+     * @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.
+     *
+     * @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
+     * ```
+     */
+    upload(data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Upload raw JSON or plain text data as a file.
+     *
+     * @example
+     * ```ts
+     * const result = await storage.uploadRaw(
+     *   { config: { theme: 'dark' } },
+     *   'settings/user-config.json',
+     *   { isPublic: false },
+     * );
+     * ```
+     */
+    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).
+     *
+     * @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`);
+     * });
+     *
+     * // Step 3: confirm
+     * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
+     * ```
+     */
+    getUploadUrl(opts: {
+        path: string;
+        mimeType: string;
+        size: number;
+        isPublic?: boolean;
+        overwrite?: boolean;
+        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.
+     */
+    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+    /**
+     * Step 3 of the recommended upload flow.
+     * Confirm a direct upload and register metadata on the server.
+     *
+     * @example
+     * ```ts
+     * const result = await storage.confirmUpload({
+     *   path: 'videos/intro.mp4',
+     *   mimeType: 'video/mp4',
+     *   isPublic: true,
+     * });
+     * console.log(result.publicUrl);
+     * ```
+     */
+    confirmUpload(opts: {
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }): Promise<UploadResult>;
+    /**
+     * Get signed upload URLs for multiple 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 });
+     * }
+     * ```
+     */
+    getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
+    /**
+     * Confirm multiple direct uploads at once.
+     */
+    batchConfirmUploads(items: Array<{
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }>): Promise<UploadResult[]>;
+    /**
+     * Download a private file as an ArrayBuffer.
+     * For public files, use the `publicUrl` directly — no SDK needed.
+     *
+     * @example
+     * ```ts
+     * const buffer = await storage.download('docs/contract.pdf');
+     * const blob = new Blob([buffer], { type: 'application/pdf' });
+     * // Open in browser:
+     * window.open(URL.createObjectURL(blob));
+     * ```
+     */
+    download(path: string): Promise<ArrayBuffer>;
+    /**
+     * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+     *
+     * @example
+     * ```ts
+     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * ```
+     */
+    batchDownload(paths: string[]): Promise<Record<string, string>>;
+    /**
+     * List files and folders at a given path prefix.
+     *
+     * @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 page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
+     * ```
+     */
+    list(opts?: ListOptions): Promise<ListResult>;
+    /**
+     * Get metadata for a file (size, MIME type, visibility, URLs).
+     *
+     * @example
+     * ```ts
+     * const meta = await storage.getMetadata('avatars/alice.jpg');
+     * console.log(meta.size, meta.isPublic, meta.publicUrl);
+     * ```
+     */
+    getMetadata(path: string): Promise<FileMetadata>;
+    /**
+     * Generate a time-limited download URL for a private file.
+     * The URL can be shared externally without requiring an `X-Storage-Key`.
+     *
+     * > **Note:** Downloads via signed URLs bypass the server, so download stats
+     * > are NOT tracked. Use `downloadUrl` for tracked downloads.
+     *
+     * @param path       Path to the file.
+     * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+     *
+     * @example
+     * ```ts
+     * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
+     * // Share signedUrl with the recipient — it expires in 30 minutes.
+     * ```
+     */
+    getSignedUrl(path: string, expiresIn?: number): Promise<SignedUrlResult>;
+    /**
+     * Change a file's visibility between public and private after upload.
+     *
+     * @example
+     * ```ts
+     * // Make a file public
+     * const result = await storage.setVisibility('avatars/alice.jpg', true);
+     * console.log(result.publicUrl); // CDN URL
+     *
+     * // Make a file private
+     * const result = await storage.setVisibility('avatars/alice.jpg', false);
+     * console.log(result.downloadUrl); // Auth-required URL
+     * ```
+     */
+    setVisibility(path: string, isPublic: boolean): Promise<{
+        path: string;
+        isPublic: boolean;
+        publicUrl: string | null;
+        downloadUrl: string | null;
+    }>;
+    /**
+     * Create a folder (a GCS prefix placeholder).
+     *
+     * @example
+     * ```ts
+     * await storage.createFolder('uploads/2025/');
+     * ```
+     */
+    createFolder(path: string): Promise<{
+        path: string;
+    }>;
+    /**
+     * Delete a single file.
+     *
+     * @example
+     * ```ts
+     * await storage.deleteFile('avatars/old-avatar.jpg');
+     * ```
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * Delete a folder and all its contents recursively.
+     *
+     * @example
+     * ```ts
+     * await storage.deleteFolder('temp/');
+     * ```
+     */
+    deleteFolder(path: string): Promise<void>;
+    /**
+     * Move or rename a file.
+     *
+     * @example
+     * ```ts
+     * // Rename
+     * await storage.move('docs/draft.pdf', 'docs/final.pdf');
+     * // Move to a different folder
+     * await storage.move('inbox/report.xlsx', 'archive/2025/report.xlsx');
+     * ```
+     */
+    move(from: string, to: string): Promise<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Copy a file to a new path.
+     *
+     * @example
+     * ```ts
+     * await storage.copy('templates/base.html', 'sites/my-site/index.html');
+     * ```
+     */
+    copy(from: string, to: string): Promise<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Get storage statistics for your key: total files, bytes, operation counts.
+     *
+     * @example
+     * ```ts
+     * const stats = await storage.getStats();
+     * console.log(`${stats.totalFiles} files, ${(stats.totalBytes / 1e6).toFixed(1)} MB`);
+     * ```
+     */
+    getStats(): Promise<StorageStats>;
+    /**
+     * Ping the storage service. No authentication required.
+     *
+     * @example
+     * ```ts
+     * const info = await storage.info();
+     * // → { ok: true, storageRoot: 'hydrous-storage' }
+     * ```
+     */
+    info(): Promise<{
+        ok: boolean;
+        storageRoot: string;
+    }>;
+}
+
+/** Accepted data types for file uploads. */
+type UploadData = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer;
+/**
+ * ScopedStorage — a StorageManager pre-scoped to a specific folder prefix.
+ *
+ * All paths are automatically prepended with the scope, so you never
+ * have to repeat the folder name.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ securityKey: 'sk_...' });
+ *
+ * // All operations in the "avatars/" folder
+ * const avatars = db.storage.scope('avatars');
+ *
+ * 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"
+ * ```
+ */
+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: UploadData, path: string, options?: UploadOptions): Promise<UploadResult>;
+    /** Upload raw JSON or text within the scoped folder. */
+    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;
+    }): Promise<UploadUrlResult>;
+    /** Upload data directly to a signed GCS URL with optional progress tracking. */
+    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+    /** Confirm a direct upload within the scoped folder. */
+    confirmUpload(opts: {
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }): Promise<UploadResult>;
+    /** Download a file within the scoped folder. */
+    download(path: string): Promise<ArrayBuffer>;
+    /** List files within the scoped folder. */
+    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. */
+    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;
+    }>;
+    /**
+     * Create a further-scoped instance nested within this scope.
+     *
+     * @example
+     * ```ts
+     * const uploads = db.storage.scope('user-uploads');
+     * const images  = uploads.scope('images'); // → "user-uploads/images/"
+     * ```
+     */
+    scope(subPrefix: string): ScopedStorage;
+}
+
+/**
+ * HydrousClient — the main entry point for the HydrousDB SDK.
+ *
+ * Create one instance per application (it is safe to share globally).
+ * Every sub-client (`auth`, `records`, `analytics`, `storage`) is lazily
+ * instantiated and cached on first access.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'hydrousdb';
+ *
+ * const db = createClient({ securityKey: 'sk_live_...' });
+ *
+ * // Records
+ * const posts   = db.records('blog-posts');
+ * const users   = db.records('app-users');
+ *
+ * // Auth
+ * const auth    = db.auth('app-users');
+ *
+ * // Analytics
+ * const stats   = db.analytics('orders');
+ *
+ * // Storage (flat)
+ * const storage = db.storage;               // StorageManager
+ *
+ * // Storage (scoped to a folder)
+ * const avatars = db.storage.scope('avatars');
+ * ```
+ */
+declare class HydrousClient {
+    private readonly http;
+    private readonly _storageKey;
+    private _storage;
+    private readonly _recordsCache;
+    private readonly _authCache;
+    private readonly _analyticsCache;
+    constructor(config: HydrousConfig);
+    /**
+     * Get a typed records client for the given bucket.
+     *
+     * The generic type parameter `T` describes the shape of records in this
+     * bucket. Leave it unset for a generic `Record<string, unknown>` shape.
+     *
+     * @param bucketKey  The name of your bucket (must match what you created in the dashboard).
+     *
+     * @example
+     * ```ts
+     * interface Post { title: string; body: string; published: boolean }
+     * const posts = db.records<Post>('blog-posts');
+     *
+     * const post = await posts.create({ title: 'Hello', body: '...', published: false });
+     * // post.id, post.createdAt, post.updatedAt are added automatically
+     * ```
+     */
+    records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
+    /**
+     * Get an auth client for the given user bucket.
+     *
+     * @param bucketKey  The name of your user bucket (e.g. `"app-users"`).
+     *
+     * @example
+     * ```ts
+     * const auth = db.auth('app-users');
+     * const { user, session } = await auth.login({ email: '...', password: '...' });
+     * ```
+     */
+    auth(bucketKey: string): AuthClient;
+    /**
+     * Get an analytics client for the given bucket.
+     *
+     * @param bucketKey  The name of the bucket to analyse.
+     *
+     * @example
+     * ```ts
+     * const analytics = db.analytics('orders');
+     * const { count } = await analytics.count();
+     * ```
+     */
+    analytics(bucketKey: string): AnalyticsClient;
+    /**
+     * The storage manager for uploading, downloading, listing, and managing files.
+     *
+     * Scoped to your project — you can never access another project's files.
+     *
+     * @example
+     * ```ts
+     * // Upload a file
+     * const result = await db.storage.upload(file, 'images/photo.jpg', { isPublic: true });
+     *
+     * // Scope to a folder
+     * const avatars = db.storage.scope('user-avatars');
+     * await avatars.upload(blob, `${userId}.jpg`, { isPublic: true });
+     * ```
+     */
+    get storage(): StorageManager & {
+        scope: (prefix: string) => ScopedStorage;
+    };
+}
+/**
+ * Create a new HydrousDB client.
+ *
+ * This is the **only** export you need to get started.
+ * The API URL is pre-configured — you only need your Security Key.
+ *
+ * @param config.securityKey  Your project's Security Key from https://hydrousdb.com/dashboard
+ * @param config.baseUrl      (Optional) Override the API base URL.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'hydrousdb';
+ *
+ * const db = createClient({
+ *   securityKey: process.env.HYDROUS_SECURITY_KEY!,
+ * });
+ * ```
+ */
+declare function createClient(config: HydrousConfig): HydrousClient;
+
+declare class HydrousError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly details?: string[];
+    constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
+    toString(): string;
+}
+declare class AuthError extends HydrousError {
+    constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
+}
+declare class RecordError extends HydrousError {
+    constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
+}
+declare class StorageError extends HydrousError {
+    constructor(message: string, code: string, status?: number, requestId?: string);
+}
+declare class AnalyticsError extends HydrousError {
+    constructor(message: string, code: string, status?: number, requestId?: string);
+}
+declare class ValidationError extends HydrousError {
+    constructor(message: string, details?: string[]);
+}
+declare class NetworkError extends HydrousError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
 
-export { AnalyticsClient, type AnalyticsEvent, type AnalyticsQueryOptions, AuthClient, type AuthSession, type AuthUser, type BatchDownloadFile, type BatchDownloadOptions, type BatchUploadOptions, type BatchUploadResult, type CallableStorage, type DownloadProgress, type FileMetadata, type Filter, type FilterOperator, HydrousClient, type HydrousConfig, HydrousDBError, type HydrousError, type HydrousResponse, type ListOptions, type ListResult, type QueryOptions, type RecordResponse, RecordsClient, ScopedStorageClient, type SignInOptions, type SignUpOptions, type SignedUrlOptions, type SignedUrlResult, type SingleRecordResponse, type StorageItem, type StorageKeys, StorageManager, type StorageStats, type TrackEventOptions, type UploadOptions, type UploadProgress, type UploadResult, type UploadStage, createClient, eq, gt, gte, inArray, isHydrousError, lt, lte, neq };
+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 };