hydrousdb 2.0.3 → 3.0.1

package/dist/index.d.ts

@@ -1,180 +1,222 @@
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+    rawBody?: string | FormData | Uint8Array<ArrayBuffer>;
+    contentType?: string;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    request<T = unknown>(path: string, apiKeyOrOpts?: string | RequestOptions, opts?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, apiKey?: string, headers?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    putToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+}
+
 /**
- * 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.
+ * Storage keys map — one named key per storage bucket/permission scope.
+ * Keys start with `ssk_`. You can define as many as you need.
  *
  * @example
- * {
+ * ```ts
+ * storageKeys: {
  *   main:      'ssk_main_…',
  *   avatars:   'ssk_avatars_…',
  *   documents: 'ssk_docs_…',
  * }
+ * ```
  */
 type StorageKeys = Record<string, string>;
 interface HydrousConfig {
-    /** Your HydrousDB project base URL */
-    url: string;
-    /** Auth service key — used for all auth.* operations */
+    /**
+     * Auth service key (starts with `hk_auth_`).
+     * Used exclusively for all `/auth/*` routes — signup, login, sessions, etc.
+     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
+     */
     authKey: string;
-    /** Bucket security key — used for records.* and analytics.* operations */
+    /**
+     * Bucket security key (starts with `hk_bucket_`).
+     * Used for all `/records/*` and `/analytics/*` routes.
+     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
+     */
     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.
+     * Named storage keys (each starts with `ssk_`).
+     * Define one key per storage bucket/permission scope.
+     * Pass the name of the key you want when calling `db.storage('keyName')`.
+     *
+     * @example
+     * ```ts
+     * storageKeys: {
+     *   main:      'ssk_main_…',      // default general-purpose bucket
+     *   avatars:   'ssk_avatars_…',   // user avatar uploads
+     *   documents: 'ssk_docs_…',      // private documents
+     * }
+     * ```
      */
     storageKeys: StorageKeys;
-    /** Optional global request timeout in milliseconds (default: 30 000) */
-    timeout?: number;
+    /**
+     * Override the API base URL. Defaults to the official HydrousDB endpoint.
+     * You almost never need to set this.
+     */
+    baseUrl?: string;
 }
-interface HydrousResponse<T = unknown> {
-    data: T | null;
-    error: HydrousError | null;
+interface SignupOptions {
+    email: string;
+    password: string;
+    fullName?: string;
+    [key: string]: unknown;
 }
-interface HydrousError {
-    message: string;
-    code: string;
-    status?: number;
+interface LoginOptions {
+    email: string;
+    password: string;
 }
-type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'nin' | 'is' | 'not';
-interface Filter {
-    field: string;
-    operator: FilterOperator;
-    value: unknown;
+interface UserRecord {
+    id: string;
+    email: 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 QueryOptions {
-    where?: Filter | Filter[];
-    orderBy?: {
-        field: string;
-        direction?: 'asc' | 'desc';
-    };
+interface Session {
+    sessionId: string;
+    userId: string;
+    bucketId: string;
+    createdAt: number;
+    expiresAt: number;
+    refreshToken: string;
+    refreshExpiresAt: number;
+}
+interface AuthResult {
+    user: UserRecord;
+    session: Session;
+}
+interface UpdateUserOptions {
+    sessionId: string;
+    userId: string;
+    data: Partial<Omit<UserRecord, 'id' | 'email' | 'createdAt'>>;
+}
+interface ChangePasswordOptions {
+    sessionId: string;
+    userId: string;
+    currentPassword: string;
+    newPassword: string;
+}
+interface ListUsersOptions {
+    sessionId: string;
     limit?: number;
     offset?: number;
-    select?: string[];
-}
-interface RecordResponse<T = Record<string, unknown>> {
-    data: T[];
-    count: number;
-    error: HydrousError | null;
 }
-interface SingleRecordResponse<T = Record<string, unknown>> {
-    data: T | null;
-    error: HydrousError | null;
+interface ListUsersResult {
+    users: UserRecord[];
+    total: number;
+    limit: number;
+    offset: number;
 }
-interface AuthUser {
+type RecordData = Record<string, unknown>;
+interface RecordResult {
     id: string;
-    email: string;
-    createdAt: string;
-    updatedAt: string;
-    metadata?: Record<string, unknown>;
+    createdAt?: number;
+    updatedAt?: number;
+    [key: string]: unknown;
 }
-interface AuthSession {
-    accessToken: string;
-    refreshToken: string;
-    expiresAt: number;
-    user: AuthUser;
+interface QueryFilter {
+    field: string;
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    value: string | number | boolean;
 }
-interface SignUpOptions {
-    email: string;
-    password: string;
-    metadata?: Record<string, unknown>;
+interface QueryOptions {
+    filters?: QueryFilter[];
+    fields?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+    startAfter?: string;
+    startAt?: string;
+    endAt?: string;
+    dateRange?: DateRange;
 }
-interface SignInOptions {
-    email: string;
-    password: string;
+interface QueryResult<T = RecordData> {
+    records: (T & RecordResult)[];
+    total?: number;
+    hasMore?: boolean;
+    nextCursor?: string;
 }
-interface TrackEventOptions {
-    event: string;
-    properties?: Record<string, unknown>;
-    userId?: string;
-    sessionId?: string;
-    timestamp?: number;
-}
-interface AnalyticsQueryOptions {
-    event?: string;
-    from?: string;
-    to?: string;
-    limit?: number;
-    groupBy?: string;
+interface PatchRecordOptions {
+    merge?: boolean;
 }
-interface AnalyticsEvent {
+interface RecordHistoryEntry {
     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;
-    total: number;
-    path: string;
-    status: 'pending' | 'success' | 'error';
-    size?: number;
+    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,276 +224,718 @@ 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 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 AnalyticsFilter {
+    field: string;
+    op: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS';
+    value: string | number | boolean;
 }
-interface ListOptions {
-    /** Folder prefix to list (empty = bucket root) */
-    prefix?: string;
+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;
-    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;
+}
+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.
+ * Uses the `authKey` (`hk_auth_…`) sent via `X-Api-Key` header.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ authKey: 'hk_auth_…', bucketSecurityKey: '…', storageKeys: { main: '…' } });
+ * const auth = db.auth('my-app-users');
+ * const { user, session } = await auth.signup({ email: 'alice@example.com', password: 'hunter2' });
+ * ```
+ */
 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;
+    private readonly http;
+    private readonly authKey;
+    private readonly basePath;
+    constructor(http: HttpClient, authKey: string, bucketKey: string);
+    private post;
+    private get;
+    private patch;
+    private delete;
+    signup(options: SignupOptions): Promise<AuthResult>;
+    login(options: LoginOptions): Promise<AuthResult>;
+    logout({ sessionId }: {
+        sessionId: string;
+    }): Promise<void>;
+    refreshSession({ refreshToken }: {
+        refreshToken: string;
+    }): Promise<Session>;
+    getUser({ userId }: {
+        userId: string;
+    }): Promise<UserRecord>;
+    updateUser(options: UpdateUserOptions): Promise<UserRecord>;
+    deleteUser({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    listUsers(options: ListUsersOptions): Promise<ListUsersResult>;
+    hardDeleteUser({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    bulkDeleteUsers({ sessionId, userIds }: {
+        sessionId: string;
+        userIds: string[];
+    }): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    lockAccount({ sessionId, userId, duration }: {
+        sessionId: string;
+        userId: string;
+        duration?: number;
+    }): Promise<{
+        lockedUntil: number;
+        unlockTime: string;
+    }>;
+    unlockAccount({ sessionId, userId }: {
+        sessionId: string;
+        userId: string;
+    }): Promise<void>;
+    changePassword(options: ChangePasswordOptions): Promise<void>;
+    requestPasswordReset({ email }: {
+        email: string;
+    }): Promise<void>;
+    confirmPasswordReset({ resetToken, newPassword }: {
+        resetToken: string;
+        newPassword: string;
+    }): Promise<void>;
+    requestEmailVerification({ userId }: {
+        userId: string;
+    }): Promise<void>;
+    confirmEmailVerification({ verifyToken }: {
+        verifyToken: string;
+    }): Promise<void>;
 }
 
-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>>;
+/**
+ * RecordsClient — CRUD + query for a single bucket.
+ * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
+ * const posts = db.records('blog-posts');
+ * const post = await posts.create({ title: 'Hello World', status: 'draft' });
+ * ```
+ */
+declare class RecordsClient<T extends RecordData = RecordData> {
+    private readonly http;
+    private readonly bucketKey;
+    private readonly basePath;
+    private readonly bucketKey_;
+    constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
+    private get key();
+    create(data: T): Promise<T & RecordResult>;
+    get(id: string): Promise<T & RecordResult>;
+    set(id: string, data: T): Promise<T & RecordResult>;
+    patch(id: string, data: Partial<T>, options?: PatchRecordOptions): Promise<T & RecordResult>;
+    delete(id: string): Promise<void>;
+    batchCreate(items: T[]): Promise<(T & RecordResult)[]>;
+    batchDelete(ids: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    query(options?: QueryOptions): Promise<QueryResult<T>>;
+    getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
+    count(filters?: QueryOptions['filters']): Promise<number>;
+    getHistory(id: string): Promise<RecordHistoryEntry[]>;
+    restoreVersion(id: string, version: number): Promise<T & RecordResult>;
 }
 
+/**
+ * AnalyticsClient — BigQuery-powered aggregations for a bucket.
+ * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
+ *
+ * @example
+ * ```ts
+ * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
+ * const analytics = db.analytics('orders');
+ * const { count } = await analytics.count();
+ * ```
+ */
 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>>;
+    private readonly http;
+    private readonly bucketSecurityKey;
+    private readonly basePath;
+    constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
+    private run;
+    count(opts?: {
+        dateRange?: DateRange;
+    }): Promise<CountResult>;
+    distribution(opts: {
+        field: string;
+        limit?: number;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<DistributionRow[]>;
+    sum(opts: {
+        field: string;
+        groupBy?: string;
+        limit?: number;
+        dateRange?: DateRange;
+    }): Promise<SumRow[]>;
+    timeSeries(opts?: {
+        granularity?: Granularity;
+        dateRange?: DateRange;
+    }): Promise<TimeSeriesRow[]>;
+    fieldTimeSeries(opts: {
+        field: string;
+        aggregation?: Aggregation;
+        granularity?: Granularity;
+        dateRange?: DateRange;
+    }): Promise<FieldTimeSeriesRow[]>;
+    topN(opts: {
+        field: string;
+        n?: number;
+        labelField?: string;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<TopNRow[]>;
+    stats(opts: {
+        field: string;
+        dateRange?: DateRange;
+    }): Promise<FieldStats>;
+    records<T extends RecordData = RecordData>(opts?: {
+        filters?: AnalyticsFilter[];
+        selectFields?: string[];
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        order?: SortOrder;
+        dateRange?: DateRange;
+    }): Promise<(T & RecordResult)[]>;
+    multiMetric(opts: {
+        metrics: MetricDefinition[];
+        dateRange?: DateRange;
+    }): Promise<MultiMetricResult>;
+    storageStats(opts?: {
+        dateRange?: DateRange;
+    }): Promise<StorageStatsResult>;
+    crossBucket(opts: {
+        bucketKeys: string[];
+        field: string;
+        aggregation?: Aggregation;
+        dateRange?: DateRange;
+    }): Promise<CrossBucketRow[]>;
+    query<T = unknown>(query: AnalyticsQuery): Promise<AnalyticsResult<T>>;
 }
 
 /**
- * A storage client that is already bound to a specific storage key.
- * You get one of these by calling  `db.storage('keyName')`.
+ * StorageManager — upload, download, list, move, copy, and delete files.
+ * Uses an `X-Storage-Key` (`ssk_…`) header — separate from auth and bucket keys.
+ * Each key is scoped to a specific storage bucket and permission set.
+ *
+ * Get a StorageManager via `db.storage('keyName')` where the key name
+ * matches one of the keys you defined in `storageKeys` when calling `createClient`.
  *
- * None of the methods on this class require you to pass a bucket key —
- * it's already baked in.
+ * @example
+ * ```ts
+ * const db = createClient({ authKey: '…', bucketSecurityKey: '…', storageKeys: { avatars: 'ssk_avatars_…' } });
+ * const avatars = db.storage('avatars');
+ * const result = await avatars.upload(file, 'alice.jpg', { isPublic: true });
+ * ```
  */
-declare class ScopedStorageClient {
-    private readonly base;
-    private readonly key;
-    readonly keyName: string;
-    constructor(baseUrl: string, keyName: string, bucketKey: string);
+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 single file.
+     * 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.
      *
-     * Supply `onProgress` to receive live upload ticks including bytes
-     * transferred, speed (bytes/sec), ETA, and lifecycle stage.
+     * @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.
      *
-     * **Stage sequence:**
-     * `pending → compressing → uploading → done | error`
+     * @example
+     * ```ts
+     * // Upload a public avatar
+     * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+     * console.log(result.publicUrl); // → https://...
      *
-     * 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.
+     * // 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, 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 result = await storage.uploadRaw(
+     *   { config: { theme: 'dark' } },
+     *   'settings/user-config.json',
+     *   { isPublic: false },
+     * );
+     * ```
      */
-    upload(file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
     /**
-     * Upload raw text or JSON content directly — no File object needed.
+     * Step 1 of the recommended upload flow.
+     * Get a signed URL to upload directly to GCS from the client (supports progress).
      *
      * @example
-     * // Save a JSON config
-     * await db.storage('configs').uploadText(
-     *   'settings/app.json',
-     *   JSON.stringify({ theme: 'dark' }),
-     *   { mimeType: 'application/json' }
-     * );
+     * ```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 });
+     * ```
      */
-    uploadText(path: string, content: string, options?: {
-        mimeType?: string;
+    getUploadUrl(opts: {
+        path: string;
+        mimeType: string;
+        size: number;
+        isPublic?: boolean;
         overwrite?: boolean;
-        onProgress?: UploadOptions['onProgress'];
-    }): Promise<HydrousResponse<UploadResult>>;
+        expiresInSeconds?: number;
+    }): Promise<UploadUrlResult>;
     /**
-     * Upload multiple files in one request.
+     * Upload data directly to a signed GCS URL (no auth headers needed).
+     * Optionally tracks progress via a callback.
      *
-     * `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.
+     * @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
-     * await db.storage('documents').batchUpload(files, {
-     *   prefix:     'reports/2024/',
-     *   onProgress: (p) => updateBar(p.index, p.percent),
+     * ```ts
+     * const result = await storage.confirmUpload({
+     *   path: 'videos/intro.mp4',
+     *   mimeType: 'video/mp4',
+     *   isPublic: true,
      * });
+     * console.log(result.publicUrl);
+     * ```
      */
-    batchUpload(files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    confirmUpload(opts: {
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }): Promise<UploadResult>;
     /**
-     * Download a single file and return its content as an `ArrayBuffer`.
+     * Get signed upload URLs for multiple files at once.
      *
      * @example
-     * const { data } = await db.storage('avatars').download('users/alice.jpg');
-     * const blob = new Blob([data!]);
-     * img.src = URL.createObjectURL(blob);
+     * ```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 });
+     * }
+     * ```
      */
-    download(filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
     /**
-     * Download multiple files in one request.
+     * 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.
      *
-     * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
+     * @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
-     * const { data } = await db.storage('reports').batchDownload(
-     *   ['jan.pdf', 'feb.pdf'],
-     *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
-     * );
+     * ```ts
+     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * ```
      */
-    batchDownload(filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    batchDownload(paths: string[]): Promise<Record<string, string>>;
     /**
-     * List files and folders (paginated).
+     * List files and folders at a given path prefix.
      *
      * @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
+     * // 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/');
+     * ```
      */
-    list(options?: ListOptions): Promise<HydrousResponse<ListResult>>;
+    createFolder(path: string): Promise<{
+        path: string;
+    }>;
     /**
-     * Get metadata for a file (size, MIME type, compression, etc.)
+     * Delete a single file.
      *
      * @example
-     * const { data: meta } = await db.storage('docs').metadata('report.pdf');
-     * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
+     * ```ts
+     * await storage.deleteFile('avatars/old-avatar.jpg');
+     * ```
      */
-    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>>;
+    deleteFile(path: string): Promise<void>;
     /**
-     * Generate a time-limited public URL for a private file.
+     * Delete a folder and all its contents recursively.
      *
      * @example
-     * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
-     * console.log(data!.signedUrl); // share this
+     * ```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`);
+     * ```
      */
-    signedUrl(filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    getStats(): Promise<StorageStats>;
     /**
-     * Get usage and billing stats for this storage key.
+     * Ping the storage service. No authentication required.
      *
      * @example
-     * const { data } = await db.storage('main').stats();
-     * console.log(data!.totalFiles, data!.totalSizeBytes);
+     * ```ts
+     * const info = await storage.info();
+     * // → { ok: true, storageRoot: 'hydrous-storage' }
+     * ```
      */
-    stats(): Promise<HydrousResponse<StorageStats>>;
+    info(): Promise<{
+        ok: boolean;
+        storageRoot: string;
+    }>;
 }
 
-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[];
+/**
+ * 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: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, 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>;
+    /** 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.
+     * `prefix` in options is relative to the scope.
+     */
+    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;
 }
+
 /**
- * The HydrousDB root client.
+ * HydrousClient — the main entry point for the HydrousDB SDK.
  *
- * Create once and reuse across your app:
+ * Each service uses its own dedicated key:
+ * - `authKey`            (`hk_auth_…`)   → `db.auth('bucket')`
+ * - `bucketSecurityKey`  (`hk_bucket_…`) → `db.records('bucket')` + `db.analytics('bucket')`
+ * - `storageKeys`        (`ssk_…`)       → `db.storage('keyName')`
  *
+ * @example
  * ```ts
  * import { createClient } from 'hydrousdb';
  *
  * const db = createClient({
- *   url:               'https://api.myapp.hydrous.app',
  *   authKey:           'hk_auth_…',
  *   bucketSecurityKey: 'hk_bucket_…',
  *   storageKeys: {
@@ -460,95 +944,137 @@ interface CallableStorage {
  *     documents: 'ssk_docs_…',
  *   },
  * });
+ *
+ * // Records & Analytics — use bucketSecurityKey automatically
+ * const posts     = db.records('blog-posts');
+ * const analytics = db.analytics('orders');
+ *
+ * // Auth — uses authKey automatically
+ * const auth = db.auth('app-users');
+ *
+ * // Storage — pick which key to use by name
+ * const avatarStorage   = db.storage('avatars');
+ * const documentStorage = db.storage('documents');
  * ```
  */
 declare class HydrousClient {
-    /** 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;
+    private readonly http;
+    private readonly authKey_;
+    private readonly bucketSecurityKey_;
+    private readonly storageKeys_;
+    private readonly _recordsCache;
+    private readonly _authCache;
+    private readonly _analyticsCache;
+    private readonly _storageCache;
+    constructor(config: HydrousConfig);
     /**
-     * Storage — call with the name of the key you want.
+     * Get a typed records client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
      *
+     * @example
      * ```ts
-     * db.storage('avatars').upload(file, { path: 'user.jpg' })
-     * db.storage('documents').list({ prefix: 'invoices/' })
-     * db.storage('main').stats()
+     * interface Post { title: string; published: boolean }
+     * const posts = db.records<Post>('blog-posts');
+     * const post = await posts.create({ title: 'Hello', published: false });
      * ```
      */
-    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);
+    records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
+    /**
+     * Get an auth client for the named user bucket.
+     * Uses your `authKey` automatically.
+     *
+     * @example
+     * ```ts
+     * const auth = db.auth('app-users');
+     * const { user, session } = await auth.login({ email: '…', password: '…' });
+     * ```
+     */
+    auth(bucketKey: string): AuthClient;
     /**
-     * Get a storage client scoped to a named key.
+     * Get an analytics client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
      *
-     * @param keyName - Must match a property you declared in `storageKeys`
+     * @example
+     * ```ts
+     * const analytics = db.analytics('orders');
+     * const { count } = await analytics.count();
+     * ```
+     */
+    analytics(bucketKey: string): AnalyticsClient;
+    /**
+     * Get a storage manager for the named storage key.
+     * The name must match a key you defined in `storageKeys` when calling `createClient`.
+     * Uses the corresponding `ssk_…` key automatically via `X-Storage-Key` header.
+     *
+     * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
      *
      * @example
-     * const avatarStore   = db.storage('avatars');
-     * const documentStore = db.storage('documents');
+     * ```ts
+     * const avatars   = db.storage('avatars');
+     * const documents = db.storage('documents');
+     *
+     * // Upload to avatars bucket
+     * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
      *
-     * await avatarStore.upload(file, { path: 'users/alice.jpg' });
-     * const list = await documentStore.list({ prefix: 'invoices/' });
+     * // Scope to a sub-folder
+     * const userDocs = db.storage('documents').scope(`users/${userId}`);
+     * await userDocs.upload(pdfBuffer, 'contract.pdf');
+     * ```
      */
-    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);
+    storage(keyName: string): StorageManager & {
+        scope: (prefix: string) => ScopedStorage;
+    };
 }
-declare function isHydrousError(err: unknown): err is HydrousDBError;
-
 /**
- * Create a HydrousDB client.
+ * Create a new HydrousDB client.
  *
  * @example
+ * ```ts
  * import { createClient } from 'hydrousdb';
  *
  * const db = createClient({
- *   url:               'https://api.myapp.hydrous.app',
- *   authKey:           'hk_auth_…',
- *   bucketSecurityKey: 'hk_bucket_…',
+ *   authKey:           process.env.HYDROUS_AUTH_KEY!,
+ *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
  *   storageKeys: {
- *     main:      'ssk_main_…',
- *     avatars:   'ssk_avatars_…',
- *     documents: 'ssk_docs_…',
+ *     main:      process.env.HYDROUS_STORAGE_MAIN!,
+ *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+ *     documents: process.env.HYDROUS_STORAGE_DOCS!,
  *   },
  * });
+ * ```
  */
 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 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 };
+declare class HydrousError extends Error {
+    /** Machine-readable error code returned by the API. */
+    readonly code: string;
+    /** HTTP status code (if applicable). */
+    readonly status?: number;
+    /** The original request ID for support tracing. */
+    readonly requestId?: string;
+    /** Additional validation details. */
+    readonly details?: string[];
+    constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
+    toString(): string;
+}
+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 };