hydrousdb 2.0.1 → 3.0.0

package/dist/index.d.ts

@@ -1,168 +1,188 @@
-interface HydrousConfig {
-    /** Your Hydrous project URL  e.g. https://api.yourapp.hydrous.app */
-    url: string;
-    /** Your project API key */
-    apiKey: string;
-    /** Optional default 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 SingleRecordResponse<T = Record<string, unknown>> {
-    data: T | null;
-    error: HydrousError | null;
+interface SignupOptions {
+    email: string;
+    password: string;
+    fullName?: string;
+    [key: string]: unknown;
 }
-interface AuthUser {
+interface LoginOptions {
+    email: string;
+    password: string;
+}
+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 TrackEventOptions {
-    event: string;
-    properties?: Record<string, unknown>;
-    userId?: string;
-    sessionId?: string;
-    timestamp?: number;
-}
-interface AnalyticsQueryOptions {
-    event?: string;
-    from?: string;
-    to?: string;
+interface ChangePasswordOptions {
+    sessionId: string;
+    userId: string;
+    currentPassword: string;
+    newPassword: 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;
-}
-/** The bucket key (ssk_…) that authorizes access to a specific storage bucket */
-type BucketKey = string;
-type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
-/** Fired for every progress tick during an upload */
-interface UploadProgress {
-    /** 0-based index (always 0 for single uploads) */
-    index: number;
-    /** Total files in this operation */
-    total: number;
-    /** Destination path (relative to your bucket root) */
-    path: string;
-    /** Current lifecycle stage */
-    stage: UploadStage;
-    /** Bytes sent to the server so far */
-    bytesUploaded: number;
-    /** Total bytes to send */
-    totalBytes: number;
-    /** 0–100 integer */
-    percent: number;
-    /** Upload speed in bytes/second – null before the first tick */
-    bytesPerSecond: number | null;
-    /** Estimated seconds remaining – null until speed is known */
-    eta: number | null;
-    /** Set when stage === 'done' */
-    result?: UploadResult;
-    /** Set when stage === 'error' */
-    error?: string;
-    /** Set when stage === 'error' */
-    code?: string;
-}
-/** Per-file progress during a batch download */
-interface DownloadProgress {
-    index: number;
+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;
@@ -170,542 +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 {
+type QueryType = 'count' | 'distribution' | 'sum' | 'timeSeries' | 'fieldTimeSeries' | 'topN' | 'stats' | 'records' | 'multiMetric' | 'storageStats' | 'crossBucket';
+type Aggregation = 'sum' | 'avg' | 'min' | 'max' | 'count';
+type Granularity = 'hour' | 'day' | 'week' | 'month' | 'year';
+type SortOrder = 'asc' | 'desc';
+interface DateRange {
+    /** Start timestamp in milliseconds (Unix epoch). */
+    start?: number;
+    /** End timestamp in milliseconds (Unix epoch). */
+    end?: number;
+}
+interface AnalyticsFilter {
+    field: string;
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    value: string | number | boolean;
+}
+interface MetricDefinition {
+    /** Field name in your records to aggregate. */
+    field: string;
+    /** Alias used in the result object. Must be a safe identifier. */
+    name: string;
+    /** Aggregation function. Defaults to 'count'. */
+    aggregation?: Aggregation;
+}
+interface AnalyticsQuery {
+    queryType: QueryType;
+    dateRange?: DateRange;
+    field?: string;
+    groupBy?: string;
+    labelField?: string;
+    aggregation?: Aggregation;
+    granularity?: Granularity;
+    filters?: AnalyticsFilter[];
+    selectFields?: string[];
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    order?: SortOrder;
+    n?: number;
+    metrics?: MetricDefinition[];
+    /** For crossBucket queries: list of bucket names to compare. */
+    bucketKeys?: string[];
+}
+interface AnalyticsResult<T = unknown> {
+    queryType: QueryType;
+    data: T;
+}
+interface CountResult {
+    count: number;
+}
+interface DistributionRow {
+    value: string | number;
+    count: number;
+}
+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;
+}
+
+/**
+ * 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');
+ *
+ * const { user, session } = await auth.signup({
+ *   email: 'alice@example.com',
+ *   password: 'hunter2',
+ *   fullName: 'Alice',
+ * });
+ * ```
+ */
+declare class AuthClient {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketKey: string);
     /**
-     * Destination path within your bucket (e.g. "avatars/photo.jpg").
-     * Defaults to the file's original name.
+     * 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',
+     * });
+     * ```
      */
-    path?: string;
+    signup(options: SignupOptions): Promise<AuthResult>;
     /**
-     * Replace the file if it already exists at the given path.
-     * @default false
+     * 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.
+     * ```
      */
-    overwrite?: boolean;
+    login(options: LoginOptions): Promise<AuthResult>;
     /**
-     * Called on every progress tick while the file is being transferred.
-     * Use this to drive progress bars, speed indicators, and ETAs.
+     * Invalidate a session (sign out).
+     *
+     * @example
+     * ```ts
+     * await auth.logout({ sessionId: session.sessionId });
+     * ```
      */
-    onProgress?: (progress: UploadProgress) => void;
-}
-interface BatchUploadOptions {
+    logout({ sessionId }: {
+        sessionId: string;
+    }): Promise<void>;
     /**
-     * Folder prefix to prepend to all file names (e.g. "uploads/2024/").
-     * Individual path overrides take precedence if provided.
+     * Extend a session using its refresh token.
+     * Returns a new session object.
+     *
+     * @example
+     * ```ts
+     * const newSession = await auth.refreshSession({ refreshToken: session.refreshToken });
+     * ```
      */
-    prefix?: string;
+    refreshSession({ refreshToken }: {
+        refreshToken: string;
+    }): Promise<Session>;
     /**
-     * Per-file destination paths in the same order as the `files` array.
-     * If omitted, `prefix + file.name` is used.
+     * Fetch a user by their ID.
+     *
+     * @example
+     * ```ts
+     * const user = await auth.getUser({ userId: 'usr_abc123' });
+     * ```
      */
-    paths?: string[];
-    /** @default false */
-    overwrite?: boolean;
-    /** Max simultaneous uploads (1–10). @default 5 */
-    concurrency?: number;
+    getUser({ userId }: {
+        userId: string;
+    }): Promise<UserRecord>;
     /**
-     * Called on every progress tick for every file.
-     * The `index` field identifies which file the event belongs to.
+     * Update fields on a user record. Requires a valid session.
+     *
+     * @example
+     * ```ts
+     * const updated = await auth.updateUser({
+     *   sessionId: session.sessionId,
+     *   userId: user.id,
+     *   data: { fullName: 'Alice Smith', plan: 'enterprise' },
+     * });
+     * ```
      */
-    onProgress?: (progress: UploadProgress) => void;
-}
-interface BatchDownloadOptions {
-    /** Max simultaneous downloads (1–10). @default 5 */
-    concurrency?: number;
+    updateUser(options: UpdateUserOptions): Promise<UserRecord>;
     /**
-     * Called when each file's download status changes.
+     * 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
+     * ```ts
+     * await auth.deleteUser({ sessionId: session.sessionId, userId: user.id });
+     * ```
      */
-    onProgress?: (progress: DownloadProgress) => void;
+    deleteUser({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
     /**
-     * When true, automatically triggers browser download for each file as
-     * it arrives. Only works in browser environments.
-     * @default false
+     * List all users in the bucket. **Admin session required.**
+     *
+     * @example
+     * ```ts
+     * const { users, total } = await auth.listUsers({
+     *   sessionId: adminSession.sessionId,
+     *   limit: 50,
+     *   offset: 0,
+     * });
+     * ```
      */
-    autoSave?: boolean;
-}
-interface ListOptions {
-    /** Folder prefix to list (e.g. "avatars/"). Empty string = root. */
-    prefix?: string;
-    /** Max items per page (1–100). @default 50 */
-    limit?: number;
-    /** Pagination cursor returned from the previous call. */
-    cursor?: string;
-}
-interface SignedUrlOptions {
-    /** How long the URL stays valid, in seconds. @default 3600 (1 hour) */
-    expiresIn?: number;
-}
-
-declare class AuthClient {
-    private readonly baseUrl;
-    private readonly headers;
-    private session;
-    constructor(config: HydrousConfig);
+    listUsers(options: ListUsersOptions): Promise<ListUsersResult>;
     /**
-     * Create a new user account and return a session.
+     * Permanently hard-delete a user and all their data. **Admin session required.**
+     * This action is irreversible.
      *
      * @example
-     * const { data, error } = await hydrous.auth.signUp({
-     *   email:    'user@example.com',
-     *   password: 'supersecret',
+     * ```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
+     * ```ts
+     * const result = await auth.bulkDeleteUsers({
+     *   sessionId: adminSession.sessionId,
+     *   userIds: ['usr_a', 'usr_b'],
      * });
+     * ```
      */
-    signUp(options: SignUpOptions): Promise<HydrousResponse<AuthSession>>;
+    bulkDeleteUsers({ sessionId, userIds, }: {
+        sessionId: string;
+        userIds: string[];
+    }): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
     /**
-     * Sign in with email and password.
+     * Lock a user account, preventing login. **Admin session required.**
+     *
+     * @param options.duration Lock duration in milliseconds. Defaults to 15 minutes.
      *
      * @example
-     * const { data, error } = await hydrous.auth.signIn({
-     *   email:    'user@example.com',
-     *   password: 'supersecret',
+     * ```ts
+     * await auth.lockAccount({
+     *   sessionId: adminSession.sessionId,
+     *   userId: user.id,
+     *   duration: 60 * 60 * 1000, // 1 hour
      * });
-     * if (data) console.log('Signed in as', data.user.email);
+     * ```
      */
-    signIn(options: SignInOptions): Promise<HydrousResponse<AuthSession>>;
+    lockAccount({ sessionId, userId, duration, }: {
+        sessionId: string;
+        userId: string;
+        duration?: number;
+    }): Promise<{
+        lockedUntil: number;
+        unlockTime: string;
+    }>;
     /**
-     * Sign out the current user and invalidate their session.
+     * Unlock a previously locked user account. **Admin session required.**
+     *
+     * @example
+     * ```ts
+     * await auth.unlockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+     * ```
      */
-    signOut(): Promise<HydrousResponse<void>>;
-    /** Return the currently authenticated user, or null if not signed in. */
-    getUser(): Promise<HydrousResponse<AuthUser>>;
+    unlockAccount({ sessionId, userId, }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
     /**
-     * Refresh the access token using the stored refresh token.
-     * Called automatically by the SDK when a 401 is received.
+     * Change a user's password. The user must supply their current password.
+     *
+     * @example
+     * ```ts
+     * await auth.changePassword({
+     *   sessionId: session.sessionId,
+     *   userId: user.id,
+     *   currentPassword: 'hunter2',
+     *   newPassword: 'correcthorsebatterystaple',
+     * });
+     * ```
      */
-    refreshSession(): Promise<HydrousResponse<AuthSession>>;
-    /** Return the current in-memory session (may be null). */
-    getSession(): AuthSession | null;
-    private _sessionHeader;
-}
-
-declare class RecordsClient {
-    private readonly baseUrl;
-    private readonly headers;
-    constructor(config: HydrousConfig);
+    changePassword(options: ChangePasswordOptions): Promise<void>;
     /**
-     * Query records from a collection.
+     * Request a password reset email for a user.
+     * Always returns success to prevent user enumeration.
      *
-     * @param collection - Collection name (e.g. "users")
-     * @param options    - Filters, ordering, pagination
+     * @example
+     * ```ts
+     * await auth.requestPasswordReset({ email: 'alice@example.com' });
+     * ```
+     */
+    requestPasswordReset({ email }: {
+        email: string;
+    }): Promise<void>;
+    /**
+     * Complete a password reset using the token from the reset email.
      *
      * @example
-     * const { data, error } = await hydrous.records.select('users', {
-     *   where:   { field: 'role', operator: 'eq', value: 'admin' },
-     *   orderBy: { field: 'createdAt', direction: 'desc' },
-     *   limit:   20,
+     * ```ts
+     * await auth.confirmPasswordReset({
+     *   resetToken: 'tok_from_email',
+     *   newPassword: 'correcthorsebatterystaple',
      * });
+     * ```
      */
-    select<T = Record<string, unknown>>(collection: string, options?: QueryOptions): Promise<RecordResponse<T>>;
+    confirmPasswordReset({ resetToken, newPassword, }: {
+        resetToken: string;
+        newPassword: string;
+    }): Promise<void>;
+    /**
+     * Send (or resend) an email verification message to a user.
+     *
+     * @example
+     * ```ts
+     * await auth.requestEmailVerification({ userId: user.id });
+     * ```
+     */
+    requestEmailVerification({ userId }: {
+        userId: string;
+    }): Promise<void>;
+    /**
+     * Confirm an email address using the token from the verification email.
+     *
+     * @example
+     * ```ts
+     * await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
+     * ```
+     */
+    confirmEmailVerification({ verifyToken }: {
+        verifyToken: string;
+    }): Promise<void>;
+}
+
+/**
+ * RecordsClient — create, read, update, delete, and query records in a bucket.
+ *
+ * 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
+ * const db = createClient({ securityKey: 'sk_...' });
+ * const posts = db.records('blog-posts');
+ *
+ * // 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 RecordsClient<T extends RecordData = RecordData> {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketKey: string);
     /**
-     * Fetch a single record by its ID.
+     * Create a new record.
      *
      * @example
-     * const { data, error } = await hydrous.records.get('users', 'user_abc123');
+     * ```ts
+     * const user = await records.create({
+     *   name: 'Alice',
+     *   email: 'alice@example.com',
+     *   score: 100,
+     * });
+     * console.log(user.id); // "rec_xxxxxxxx"
+     * ```
      */
-    get<T = Record<string, unknown>>(collection: string, id: string): Promise<SingleRecordResponse<T>>;
+    create(data: T): Promise<T & RecordResult>;
     /**
-     * Insert one or more records into a collection.
+     * Fetch a single record by ID.
      *
-     * @param collection - Collection name
-     * @param payload    - A single record object or an array of record objects
+     * @example
+     * ```ts
+     * const post = await records.get('rec_abc123');
+     * ```
+     */
+    get(id: string): Promise<T & RecordResult>;
+    /**
+     * Overwrite a record entirely (full replace).
      *
      * @example
-     * // Single insert
-     * const { data, error } = await hydrous.records.insert('users', {
-     *   name: 'Alice', email: 'alice@example.com'
+     * ```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
+     * ```ts
+     * // Merge: only the provided fields are updated
+     * const updated = await records.patch('rec_abc123', { score: 200 });
      *
-     * // Bulk insert
-     * const { data, error } = await hydrous.records.insert('users', [
-     *   { name: 'Alice' }, { name: 'Bob' }
+     * // Replace: equivalent to set()
+     * const replaced = await records.patch('rec_abc123', { score: 200 }, { merge: false });
+     * ```
+     */
+    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']);
+     * ```
      */
-    insert<T = Record<string, unknown>>(collection: string, payload: Partial<T> | Partial<T>[]): Promise<RecordResponse<T>>;
+    batchDelete(ids: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
     /**
-     * Update a record by ID.
+     * Query records with optional filters, sorting, and pagination.
      *
      * @example
-     * const { data, error } = await hydrous.records.update('users', 'user_abc123', {
-     *   name: 'Alice Smith'
+     * ```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 });
+     * ```
      */
-    update<T = Record<string, unknown>>(collection: string, id: string, payload: Partial<T>): Promise<SingleRecordResponse<T>>;
+    getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
     /**
-     * Delete a record by ID.
+     * Count records matching optional filters.
      *
      * @example
-     * const { error } = await hydrous.records.delete('users', 'user_abc123');
+     * ```ts
+     * const total = await posts.count([{ field: 'status', op: '==', value: 'published' }]);
+     * ```
      */
-    delete(collection: string, id: string): Promise<SingleRecordResponse<void>>;
+    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 baseUrl;
-    private readonly headers;
-    constructor(config: HydrousConfig);
+    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;
     /**
-     * Track an analytics event.
+     * Count the total number of records in the bucket, with optional date filter.
      *
      * @example
-     * await hydrous.analytics.track({
-     *   event:      'page_view',
-     *   properties: { page: '/home', referrer: 'google.com' },
-     *   userId:     'user_abc123',
+     * ```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() },
      * });
+     * ```
      */
-    track(options: TrackEventOptions): Promise<HydrousResponse<void>>;
+    count(opts?: {
+        dateRange?: DateRange;
+    }): Promise<CountResult>;
     /**
-     * Query recorded analytics events.
+     * Count how many records have each unique value for a given field.
+     * Great for pie charts and bar charts.
      *
      * @example
-     * const { data } = await hydrous.analytics.query({
-     *   event: 'page_view',
-     *   from:  '2024-01-01',
-     *   to:    '2024-01-31',
-     *   limit: 100,
+     * ```ts
+     * const rows = await analytics.distribution({
+     *   field: 'status',
+     *   limit: 10,
+     *   order: 'desc',
      * });
+     * // → [{ value: 'completed', count: 312 }, { value: 'pending', count: 88 }, ...]
+     * ```
      */
-    query(options?: AnalyticsQueryOptions): Promise<RecordResponse<AnalyticsEvent>>;
+    distribution(opts: {
+        field: string;
+        limit?: number;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<DistributionRow[]>;
     /**
-     * Track multiple events in a single request (more efficient than
-     * calling `track` in a loop).
+     * Sum a numeric field, optionally grouped by another field.
      *
      * @example
-     * await hydrous.analytics.trackBatch([
-     *   { event: 'signup',   userId: 'u1' },
-     *   { event: 'onboarded', userId: 'u1' },
-     * ]);
+     * ```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 }, ...]
+     * ```
      */
-    trackBatch(events: TrackEventOptions[]): Promise<HydrousResponse<void>>;
-}
-
-declare class StorageClient {
-    private readonly baseUrl;
-    constructor(config: HydrousConfig);
+    sum(opts: {
+        field: string;
+        groupBy?: string;
+        limit?: number;
+        dateRange?: DateRange;
+    }): Promise<SumRow[]>;
     /**
-     * Upload a single file to a bucket.
-     *
-     * The bucket key **always comes first**.
-     * Supply an `onProgress` callback to receive live upload progress including
-     * bytes transferred, speed (bytes/sec), ETA, and lifecycle stage.
-     *
-     * ### Stages fired via `onProgress`
-     * | Stage        | Meaning                                 |
-     * |-------------|------------------------------------------|
-     * | `pending`   | Queued, not yet started                 |
-     * | `compressing` | Server is compressing the file         |
-     * | `uploading` | Bytes flowing to cloud storage           |
-     * | `done`      | Confirmed written to cloud storage       |
-     * | `error`     | Something went wrong                    |
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param file       A `File`, `Blob`, or `Buffer` (Node)
-     * @param options    Path, overwrite flag, progress callback
-     *
-     * @example
-     * const { data, error } = await hydrous.storage.upload(
-     *   'ssk_my_bucket_key',
-     *   file,
-     *   {
-     *     path:       'avatars/alice.jpg',
-     *     overwrite:  true,
-     *     onProgress: (p) => {
-     *       console.log(`${p.stage} — ${p.percent}%  ${p.bytesPerSecond} B/s  ETA ${p.eta}s`);
-     *     },
-     *   }
-     * );
+     * 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 }, ...]
+     * ```
      */
-    upload(bucketKey: BucketKey, file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    timeSeries(opts?: {
+        granularity?: Granularity;
+        dateRange?: DateRange;
+    }): Promise<TimeSeriesRow[]>;
     /**
-     * Upload raw text or JSON content directly — no `File` object needed.
-     * Great for saving generated content, config files, or JSON records.
+     * Aggregate a numeric field over time (e.g. daily revenue, hourly signups).
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param path       Destination path (e.g. `"configs/settings.json"`)
-     * @param content    String content to store
-     * @param options    `mimeType`, `overwrite`, `onProgress`
+     * @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
-     * await hydrous.storage.uploadText(
-     *   'ssk_my_bucket_key',
-     *   'reports/summary.txt',
-     *   'Hello from Hydrous!',
-     *   { mimeType: 'text/plain' }
-     * );
+     * ```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 }, ...]
+     * ```
      */
-    uploadText(bucketKey: BucketKey, path: string, content: string, options?: {
-        mimeType?: string;
-        overwrite?: boolean;
-        onProgress?: UploadOptions['onProgress'];
-    }): Promise<HydrousResponse<UploadResult>>;
-    /**
-     * Upload multiple files in one request.
-     *
-     * `onProgress` fires for **every file individually** — the `index` field
-     * tells you which file the event belongs to (0-based, same order as `files`).
-     * All files receive a `pending` event upfront before any uploads start,
-     * so you can render all progress bars immediately.
-     *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param files      Array of `File` objects (browser) or `{ name, data }` objects (Node)
-     * @param options    Prefix, per-file paths, overwrite, concurrency, onProgress
-     *
-     * @example
-     * await hydrous.storage.batchUpload(
-     *   'ssk_my_bucket_key',
-     *   fileArray,
-     *   {
-     *     prefix:     'uploads/2024/',
-     *     onProgress: (p) => {
-     *       console.log(`File ${p.index}: ${p.stage} ${p.percent}%`);
-     *     },
-     *   }
-     * );
+    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 }
+     * ```
      */
-    batchUpload(bucketKey: BucketKey, files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    stats(opts: {
+        field: string;
+        dateRange?: DateRange;
+    }): Promise<FieldStats>;
     /**
-     * Download a single file and return its content as an `ArrayBuffer`.
+     * Query raw records with filters, field selection, and pagination.
+     * This is the analytics version of `records.query()` but powered by BigQuery.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file within your bucket
+     * @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
-     * const { data, error } = await hydrous.storage.download(
-     *   'ssk_my_bucket_key',
-     *   'avatars/alice.jpg'
-     * );
-     * if (data) {
-     *   const blob = new Blob([data]);
-     *   const url  = URL.createObjectURL(blob);
-     * }
+     * ```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 }
+     * ```
      */
-    download(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    multiMetric(opts: {
+        metrics: MetricDefinition[];
+        dateRange?: DateRange;
+    }): Promise<MultiMetricResult>;
     /**
-     * Download multiple files in one request.
+     * Get storage statistics for this bucket: record counts, byte sizes.
      *
-     * When `autoSave: true` (browser only) each file is automatically saved
-     * to the user's Downloads folder as it arrives.
+     * @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.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePaths  Array of file paths within your bucket
-     * @param options    Concurrency, onProgress, autoSave
+     * @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
-     * const { data } = await hydrous.storage.batchDownload(
-     *   'ssk_my_bucket_key',
-     *   ['reports/jan.pdf', 'reports/feb.pdf'],
-     *   {
-     *     onProgress: (p) => console.log(p.path, p.status),
-     *     autoSave:   true,  // triggers browser file-save dialog per file
-     *   }
-     * );
+     * ```ts
+     * const result = await analytics.query({
+     *   queryType: 'topN',
+     *   field: 'category',
+     *   n: 3,
+     *   order: 'asc',
+     * });
+     * ```
      */
-    batchDownload(bucketKey: BucketKey, filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    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();
     /**
-     * List files and folders inside a bucket (or a folder within it).
+     * 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.
      *
-     * Results are paginated — use `pagination.nextCursor` to fetch the next page.
+     * @example
+     * ```ts
+     * // Upload a public avatar
+     * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+     * console.log(result.publicUrl); // → https://...
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param options    `prefix`, `limit`, `cursor`
+     * // 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
-     * const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
-     *   prefix: 'avatars/',
-     *   limit:  50,
+     * ```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,
      * });
-     * for (const item of data.items) {
-     *   console.log(item.type, item.path);
-     * }
+     *
+     * // 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 });
+     * ```
      */
-    list(bucketKey: BucketKey, options?: ListOptions): Promise<HydrousResponse<ListResult>>;
+    getUploadUrl(opts: {
+        path: string;
+        mimeType: string;
+        size: number;
+        isPublic?: boolean;
+        overwrite?: boolean;
+        expiresInSeconds?: number;
+    }): Promise<UploadUrlResult>;
     /**
-     * Get metadata for a specific file (size, MIME type, compression info, etc.)
+     * Upload data directly to a signed GCS URL (no auth headers needed).
+     * Optionally tracks progress via a callback.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file within your bucket
+     * @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
-     * const { data } = await hydrous.storage.metadata(
-     *   'ssk_my_bucket_key',
-     *   'avatars/alice.jpg'
-     * );
-     * console.log(data.size, data.mimeType);
+     * ```ts
+     * const result = await storage.confirmUpload({
+     *   path: 'videos/intro.mp4',
+     *   mimeType: 'video/mp4',
+     *   isPublic: true,
+     * });
+     * console.log(result.publicUrl);
+     * ```
      */
-    metadata(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<FileMetadata>>;
+    confirmUpload(opts: {
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }): Promise<UploadResult>;
     /**
-     * Delete a single file.
+     * 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.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file to delete
+     * @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
-     * await hydrous.storage.deleteFile('ssk_my_bucket_key', 'avatars/old.jpg');
+     * ```ts
+     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * ```
      */
-    deleteFile(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<void>>;
+    batchDownload(paths: string[]): Promise<Record<string, string>>;
     /**
-     * Recursively delete a folder and all of its contents.
+     * List files and folders at a given path prefix.
      *
-     * @param bucketKey   Your storage bucket key (`ssk_…`)
-     * @param folderPath  Folder path to delete (e.g. `"old-uploads/"`)
+     * @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
-     * await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+     * ```ts
+     * const meta = await storage.getMetadata('avatars/alice.jpg');
+     * console.log(meta.size, meta.isPublic, meta.publicUrl);
+     * ```
      */
-    deleteFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
+    getMetadata(path: string): Promise<FileMetadata>;
     /**
-     * Create an empty folder.
+     * 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 bucketKey   Your storage bucket key (`ssk_…`)
-     * @param folderPath  Path for the new folder (e.g. `"avatars/2024/"`)
+     * @param path       Path to the file.
+     * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
      *
      * @example
-     * await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
+     * ```ts
+     * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
+     * // Share signedUrl with the recipient — it expires in 30 minutes.
+     * ```
      */
-    createFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
+    getSignedUrl(path: string, expiresIn?: number): Promise<SignedUrlResult>;
     /**
-     * Move (rename) a file to a new path.
+     * Change a file's visibility between public and private after upload.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param fromPath   Current path of the file
-     * @param toPath     New path for the file
+     * @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
-     * await hydrous.storage.move(
-     *   'ssk_my_bucket_key',
-     *   'drafts/report.pdf',
-     *   'published/report.pdf'
-     * );
+     * ```ts
+     * await storage.createFolder('uploads/2025/');
+     * ```
      */
-    move(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    createFolder(path: string): Promise<{
+        path: string;
+    }>;
     /**
-     * Copy a file to a new path (original is kept).
+     * Delete a single file.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param fromPath   Source path
-     * @param toPath     Destination path
+     * @example
+     * ```ts
+     * await storage.deleteFile('avatars/old-avatar.jpg');
+     * ```
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * Delete a folder and all its contents recursively.
      *
      * @example
-     * await hydrous.storage.copy(
-     *   'ssk_my_bucket_key',
-     *   'templates/invoice.pdf',
-     *   'invoices/invoice-001.pdf'
-     * );
+     * ```ts
+     * await storage.deleteFolder('temp/');
+     * ```
      */
-    copy(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    deleteFolder(path: string): Promise<void>;
     /**
-     * Generate a time-limited public URL for a private file.
+     * Move or rename a file.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
-     * @param filePath   Path of the file
-     * @param options    `expiresIn` seconds (default: 3600)
+     * @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
-     * const { data } = await hydrous.storage.signedUrl(
-     *   'ssk_my_bucket_key',
-     *   'private/contract.pdf',
-     *   { expiresIn: 300 }   // 5 minutes
-     * );
-     * console.log(data.signedUrl);  // share this URL
+     * ```ts
+     * await storage.copy('templates/base.html', 'sites/my-site/index.html');
+     * ```
      */
-    signedUrl(bucketKey: BucketKey, filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    copy(from: string, to: string): Promise<{
+        from: string;
+        to: string;
+    }>;
     /**
-     * Get usage and billing statistics for this bucket key.
+     * Get storage statistics for your key: total files, bytes, operation counts.
      *
-     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @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
-     * const { data } = await hydrous.storage.stats('ssk_my_bucket_key');
-     * console.log(`${data.totalFiles} files, ${data.totalSizeBytes} bytes stored`);
+     * ```ts
+     * const info = await storage.info();
+     * // → { ok: true, storageRoot: 'hydrous-storage' }
+     * ```
      */
-    stats(bucketKey: BucketKey): Promise<HydrousResponse<StorageStats>>;
+    info(): Promise<{
+        ok: boolean;
+        storageRoot: string;
+    }>;
 }
 
+/** Accepted data types for file uploads. */
+type UploadData = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer;
 /**
- * The root Hydrous client.
+ * ScopedStorage — a StorageManager pre-scoped to a specific folder prefix.
  *
- * Instantiate once and reuse throughout your app.
+ * All paths are automatically prepended with the scope, so you never
+ * have to repeat the folder name.
  *
  * @example
- * import { HydrousClient } from 'hydrous';
+ * ```ts
+ * const db = createClient({ securityKey: 'sk_...' });
  *
- * const hydrous = new HydrousClient({
- *   url:    'https://api.myapp.hydrous.app',
- *   apiKey: 'hk_live_…',
- * });
+ * // 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 HydrousClient {
-    /** Authentication — sign up, sign in, sign out, session management */
-    readonly auth: AuthClient;
-    /** Records — insert, select, update, delete structured data */
-    readonly records: RecordsClient;
-    /** Analytics — track events, query event history */
-    readonly analytics: AnalyticsClient;
+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;
+    }>;
     /**
-     * Storage — upload, download, list, move, delete files.
+     * Create a further-scoped instance nested within this scope.
      *
-     * Every method takes a **bucket key** (`ssk_…`) as its **first argument**.
+     * @example
+     * ```ts
+     * const uploads = db.storage.scope('user-uploads');
+     * const images  = uploads.scope('images'); // → "user-uploads/images/"
+     * ```
      */
-    readonly storage: StorageClient;
-    constructor(config: HydrousConfig);
+    scope(subPrefix: string): ScopedStorage;
 }
 
-/** Shorthand helper: creates a simple equality filter */
-declare function eq(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "not equal" filter */
-declare function neq(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "greater than" filter */
-declare function gt(field: string, value: unknown): Filter;
-/** Shorthand helper: creates a "less than" filter */
-declare function lt(field: string, value: unknown): Filter;
-/** Shorthand helper: creates an "in array" filter */
-declare function inArray(field: string, value: unknown[]): Filter;
-
-declare class HydrousSDKError extends Error {
-    readonly code: string;
-    readonly status: number | undefined;
-    constructor(message: string, code?: string, status?: number);
+/**
+ * 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;
+    };
 }
-declare function isHydrousError(err: unknown): err is HydrousSDKError;
-
 /**
- * Create and return a `HydrousClient` instance.
+ * 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
- * import { createClient } from 'hydrous';
+ * ```ts
+ * import { createClient } from 'hydrousdb';
  *
- * const hydrous = createClient({
- *   url:    'https://api.myapp.hydrous.app',
- *   apiKey: 'hk_live_…',
+ * const db = createClient({
+ *   securityKey: process.env.HYDROUS_SECURITY_KEY!,
  * });
+ * ```
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
-export { AnalyticsClient, type AnalyticsEvent, type AnalyticsQueryOptions, AuthClient, type AuthSession, type AuthUser, type BatchDownloadFile, type BatchDownloadOptions, type BatchUploadOptions, type BatchUploadResult, type BucketKey, type DownloadProgress, type FileMetadata, type Filter, type FilterOperator, HydrousClient, type HydrousConfig, type HydrousError, type HydrousResponse, HydrousSDKError, type ListOptions, type ListResult, type QueryOptions, type RecordResponse, RecordsClient, type SignInOptions, type SignUpOptions, type SignedUrlOptions, type SignedUrlResult, type SingleRecordResponse, StorageClient, type StorageItem, type StorageStats, type TrackEventOptions, type UploadOptions, type UploadProgress, type UploadResult, type UploadStage, createClient, eq, gt, inArray, isHydrousError, lt, neq };
+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 { 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 };