hydrousdb 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -1,79 +1,711 @@
-import { RecordsClient } from './records/index.js';
-export { BucketOptions } from './records/index.js';
-import { AuthClient } from './auth/index.js';
-import { AnalyticsClient } from './analytics/index.js';
-import { H as HydrousErrorBody, a as HydrousConfig } from './http-DTukpdAU.js';
-export { A as AccountLockPayload, b as AccountLockResponse, c as AnalyticsQuery, d as AnalyticsQueryType, e as AnalyticsResponse, f as ApiMeta, g as AuthUser, B as BatchDeletePayload, h as BatchDeleteResponse, i as BatchInsertPayload, j as BatchInsertResponse, k as BatchResult, l as BatchUpdateItem, m as BatchUpdatePayload, n as BatchUpdateResponse, C as CountResult, D as DateRange, o as DeleteRecordResponse, p as DistributionItem, E as EmailVerifyConfirmPayload, q as EmailVerifyRequestPayload, F as FieldStatsResult, r as FieldTimeSeriesPoint, s as Filter, t as FilterOp, u as FilteredRecordsResult, G as GetRecordOptions, v as GetRecordResponse, w as GetSnapshotResponse, x as GetUserResponse, y as HistoryEntry, z as HydrousRecord, I as InsertRecordPayload, J as InsertRecordResponse, L as ListUsersResponse, M as MultiMetricItem, P as PaginationMeta, K as PasswordChangePayload, N as PasswordResetConfirmPayload, O as PasswordResetRequestPayload, Q as QueryOptions, R as QueryResponse, S as RecordData, T as RecordExistsInfo, U as RefreshSessionResponse, V as RequestOptions, W as SessionInfo, X as SignInPayload, Y as SignInResponse, Z as SignOutPayload, _ as SignUpPayload, $ as SignUpResponse, a0 as StorageStatsResult, a1 as SumResult, a2 as TimeSeriesPoint, a3 as TopNItem, a4 as UpdateRecordPayload, a5 as UpdateRecordResponse, a6 as UpdateUserPayload, a7 as UpdateUserResponse, a8 as ValidateSessionResponse } from './http-DTukpdAU.js';
+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 QueryOptions {
+    where?: Filter | Filter[];
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    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 AuthUser {
+    id: string;
+    email: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface AuthSession {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    user: AuthUser;
+}
+interface SignUpOptions {
+    email: string;
+    password: string;
+    metadata?: Record<string, unknown>;
+}
+interface SignInOptions {
+    email: string;
+    password: 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 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;
+    total: number;
+    path: string;
+    status: 'pending' | 'success' | 'error';
+    size?: number;
+    mimeType?: string;
+    error?: string;
+}
+interface UploadResult {
+    path: string;
+    compressed: boolean;
+    originalSize: number;
+    storedSize: number;
+    spaceSaved: number;
+    mimeType: string;
+}
+interface FileMetadata {
+    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 {
+    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;
+}
+interface ListResult {
+    items: StorageItem[];
+    pagination: {
+        limit: number;
+        count: number;
+        hasNextPage: boolean;
+        nextCursor: string | null;
+    };
+}
+interface SignedUrlResult {
+    signedUrl: string;
+    expiresAt: string;
+    expiresIn: number;
+    path: string;
+}
+interface BatchUploadResult {
+    succeeded: UploadResult[];
+    failed: Array<{
+        path: string;
+        error: string;
+        code: string;
+    }>;
+}
+interface BatchDownloadFile {
+    path: string;
+    content: ArrayBuffer;
+    mimeType: string;
+    size: number;
+}
+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 UploadOptions {
+    /**
+     * Destination path within your bucket (e.g. "avatars/photo.jpg").
+     * Defaults to the file's original name.
+     */
+    path?: string;
+    /**
+     * Replace the file if it already exists at the given path.
+     * @default false
+     */
+    overwrite?: boolean;
+    /**
+     * Called on every progress tick while the file is being transferred.
+     * Use this to drive progress bars, speed indicators, and ETAs.
+     */
+    onProgress?: (progress: UploadProgress) => void;
+}
+interface BatchUploadOptions {
+    /**
+     * Folder prefix to prepend to all file names (e.g. "uploads/2024/").
+     * Individual path overrides take precedence if provided.
+     */
+    prefix?: string;
+    /**
+     * Per-file destination paths in the same order as the `files` array.
+     * If omitted, `prefix + file.name` is used.
+     */
+    paths?: string[];
+    /** @default false */
+    overwrite?: boolean;
+    /** Max simultaneous uploads (1–10). @default 5 */
+    concurrency?: number;
+    /**
+     * Called on every progress tick for every file.
+     * The `index` field identifies which file the event belongs to.
+     */
+    onProgress?: (progress: UploadProgress) => void;
+}
+interface BatchDownloadOptions {
+    /** Max simultaneous downloads (1–10). @default 5 */
+    concurrency?: number;
+    /**
+     * Called when each file's download status changes.
+     */
+    onProgress?: (progress: DownloadProgress) => void;
+    /**
+     * When true, automatically triggers browser download for each file as
+     * it arrives. Only works in browser environments.
+     * @default false
+     */
+    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;
+}
 
-/**
- * Thrown for any non-2xx response from the HydrousDB API.
- */
-declare class HydrousError extends Error {
-    /** HTTP status code */
-    readonly status: number;
-    /** Machine-readable error code from the API */
-    readonly code: string | undefined;
-    /** Detailed validation messages */
-    readonly details: string[];
-    /** Server-generated request ID for support */
-    readonly requestId: string | undefined;
-    constructor(body: HydrousErrorBody, status: number);
+declare class AuthClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private session;
+    constructor(config: HydrousConfig);
+    /**
+     * Create a new user account and return a session.
+     *
+     * @example
+     * const { data, error } = await hydrous.auth.signUp({
+     *   email:    'user@example.com',
+     *   password: 'supersecret',
+     * });
+     */
+    signUp(options: SignUpOptions): Promise<HydrousResponse<AuthSession>>;
+    /**
+     * Sign in with email and password.
+     *
+     * @example
+     * const { data, error } = await hydrous.auth.signIn({
+     *   email:    'user@example.com',
+     *   password: 'supersecret',
+     * });
+     * if (data) console.log('Signed in as', data.user.email);
+     */
+    signIn(options: SignInOptions): Promise<HydrousResponse<AuthSession>>;
+    /**
+     * Sign out the current user and invalidate their session.
+     */
+    signOut(): Promise<HydrousResponse<void>>;
+    /** Return the currently authenticated user, or null if not signed in. */
+    getUser(): Promise<HydrousResponse<AuthUser>>;
+    /**
+     * Refresh the access token using the stored refresh token.
+     * Called automatically by the SDK when a 401 is received.
+     */
+    refreshSession(): Promise<HydrousResponse<AuthSession>>;
+    /** Return the current in-memory session (may be null). */
+    getSession(): AuthSession | null;
+    private _sessionHeader;
 }
-/**
- * Thrown when a network request fails (e.g. no connectivity, DNS failure).
- */
-declare class HydrousNetworkError extends Error {
-    readonly cause: unknown;
-    constructor(message: string, cause?: unknown);
+
+declare class RecordsClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(config: HydrousConfig);
+    /**
+     * Query records from a collection.
+     *
+     * @param collection - Collection name (e.g. "users")
+     * @param options    - Filters, ordering, pagination
+     *
+     * @example
+     * const { data, error } = await hydrous.records.select('users', {
+     *   where:   { field: 'role', operator: 'eq', value: 'admin' },
+     *   orderBy: { field: 'createdAt', direction: 'desc' },
+     *   limit:   20,
+     * });
+     */
+    select<T = Record<string, unknown>>(collection: string, options?: QueryOptions): Promise<RecordResponse<T>>;
+    /**
+     * Fetch a single record by its ID.
+     *
+     * @example
+     * const { data, error } = await hydrous.records.get('users', 'user_abc123');
+     */
+    get<T = Record<string, unknown>>(collection: string, id: string): Promise<SingleRecordResponse<T>>;
+    /**
+     * Insert one or more records into a collection.
+     *
+     * @param collection - Collection name
+     * @param payload    - A single record object or an array of record objects
+     *
+     * @example
+     * // Single insert
+     * const { data, error } = await hydrous.records.insert('users', {
+     *   name: 'Alice', email: 'alice@example.com'
+     * });
+     *
+     * // Bulk insert
+     * const { data, error } = await hydrous.records.insert('users', [
+     *   { name: 'Alice' }, { name: 'Bob' }
+     * ]);
+     */
+    insert<T = Record<string, unknown>>(collection: string, payload: Partial<T> | Partial<T>[]): Promise<RecordResponse<T>>;
+    /**
+     * Update a record by ID.
+     *
+     * @example
+     * const { data, error } = await hydrous.records.update('users', 'user_abc123', {
+     *   name: 'Alice Smith'
+     * });
+     */
+    update<T = Record<string, unknown>>(collection: string, id: string, payload: Partial<T>): Promise<SingleRecordResponse<T>>;
+    /**
+     * Delete a record by ID.
+     *
+     * @example
+     * const { error } = await hydrous.records.delete('users', 'user_abc123');
+     */
+    delete(collection: string, id: string): Promise<SingleRecordResponse<void>>;
 }
-/**
- * Thrown when a request exceeds the configured timeout.
- */
-declare class HydrousTimeoutError extends Error {
-    constructor(timeoutMs: number);
+
+declare class AnalyticsClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(config: HydrousConfig);
+    /**
+     * Track an analytics event.
+     *
+     * @example
+     * await hydrous.analytics.track({
+     *   event:      'page_view',
+     *   properties: { page: '/home', referrer: 'google.com' },
+     *   userId:     'user_abc123',
+     * });
+     */
+    track(options: TrackEventOptions): Promise<HydrousResponse<void>>;
+    /**
+     * Query recorded analytics events.
+     *
+     * @example
+     * const { data } = await hydrous.analytics.query({
+     *   event: 'page_view',
+     *   from:  '2024-01-01',
+     *   to:    '2024-01-31',
+     *   limit: 100,
+     * });
+     */
+    query(options?: AnalyticsQueryOptions): Promise<RecordResponse<AnalyticsEvent>>;
+    /**
+     * Track multiple events in a single request (more efficient than
+     * calling `track` in a loop).
+     *
+     * @example
+     * await hydrous.analytics.trackBatch([
+     *   { event: 'signup',   userId: 'u1' },
+     *   { event: 'onboarded', userId: 'u1' },
+     * ]);
+     */
+    trackBatch(events: TrackEventOptions[]): Promise<HydrousResponse<void>>;
+}
+
+declare class StorageClient {
+    private readonly baseUrl;
+    constructor(config: HydrousConfig);
+    /**
+     * 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`);
+     *     },
+     *   }
+     * );
+     */
+    upload(bucketKey: BucketKey, file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    /**
+     * Upload raw text or JSON content directly — no `File` object needed.
+     * Great for saving generated content, config files, or JSON records.
+     *
+     * @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
+     * await hydrous.storage.uploadText(
+     *   'ssk_my_bucket_key',
+     *   'reports/summary.txt',
+     *   'Hello from Hydrous!',
+     *   { mimeType: 'text/plain' }
+     * );
+     */
+    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}%`);
+     *     },
+     *   }
+     * );
+     */
+    batchUpload(bucketKey: BucketKey, files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    /**
+     * Download a single file and return its content as an `ArrayBuffer`.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param filePath   Path of the file within your bucket
+     *
+     * @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);
+     * }
+     */
+    download(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    /**
+     * Download multiple files in one request.
+     *
+     * When `autoSave: true` (browser only) each file is automatically saved
+     * to the user's Downloads folder as it arrives.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param filePaths  Array of file paths within your bucket
+     * @param options    Concurrency, onProgress, autoSave
+     *
+     * @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
+     *   }
+     * );
+     */
+    batchDownload(bucketKey: BucketKey, filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    /**
+     * List files and folders inside a bucket (or a folder within it).
+     *
+     * Results are paginated — use `pagination.nextCursor` to fetch the next page.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param options    `prefix`, `limit`, `cursor`
+     *
+     * @example
+     * const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
+     *   prefix: 'avatars/',
+     *   limit:  50,
+     * });
+     * for (const item of data.items) {
+     *   console.log(item.type, item.path);
+     * }
+     */
+    list(bucketKey: BucketKey, options?: ListOptions): Promise<HydrousResponse<ListResult>>;
+    /**
+     * Get metadata for a specific file (size, MIME type, compression info, etc.)
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param filePath   Path of the file within your bucket
+     *
+     * @example
+     * const { data } = await hydrous.storage.metadata(
+     *   'ssk_my_bucket_key',
+     *   'avatars/alice.jpg'
+     * );
+     * console.log(data.size, data.mimeType);
+     */
+    metadata(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<FileMetadata>>;
+    /**
+     * Delete a single file.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param filePath   Path of the file to delete
+     *
+     * @example
+     * await hydrous.storage.deleteFile('ssk_my_bucket_key', 'avatars/old.jpg');
+     */
+    deleteFile(bucketKey: BucketKey, filePath: string): Promise<HydrousResponse<void>>;
+    /**
+     * Recursively delete a folder and all of its contents.
+     *
+     * @param bucketKey   Your storage bucket key (`ssk_…`)
+     * @param folderPath  Folder path to delete (e.g. `"old-uploads/"`)
+     *
+     * @example
+     * await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+     */
+    deleteFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
+    /**
+     * Create an empty folder.
+     *
+     * @param bucketKey   Your storage bucket key (`ssk_…`)
+     * @param folderPath  Path for the new folder (e.g. `"avatars/2024/"`)
+     *
+     * @example
+     * await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
+     */
+    createFolder(bucketKey: BucketKey, folderPath: string): Promise<HydrousResponse<void>>;
+    /**
+     * Move (rename) a file to a new path.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param fromPath   Current path of the file
+     * @param toPath     New path for the file
+     *
+     * @example
+     * await hydrous.storage.move(
+     *   'ssk_my_bucket_key',
+     *   'drafts/report.pdf',
+     *   'published/report.pdf'
+     * );
+     */
+    move(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    /**
+     * Copy a file to a new path (original is kept).
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param fromPath   Source path
+     * @param toPath     Destination path
+     *
+     * @example
+     * await hydrous.storage.copy(
+     *   'ssk_my_bucket_key',
+     *   'templates/invoice.pdf',
+     *   'invoices/invoice-001.pdf'
+     * );
+     */
+    copy(bucketKey: BucketKey, fromPath: string, toPath: string): Promise<HydrousResponse<void>>;
+    /**
+     * Generate a time-limited public URL for a private file.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     * @param filePath   Path of the file
+     * @param options    `expiresIn` seconds (default: 3600)
+     *
+     * @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
+     */
+    signedUrl(bucketKey: BucketKey, filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    /**
+     * Get usage and billing statistics for this bucket key.
+     *
+     * @param bucketKey  Your storage bucket key (`ssk_…`)
+     *
+     * @example
+     * const { data } = await hydrous.storage.stats('ssk_my_bucket_key');
+     * console.log(`${data.totalFiles} files, ${data.totalSizeBytes} bytes stored`);
+     */
+    stats(bucketKey: BucketKey): Promise<HydrousResponse<StorageStats>>;
 }
 
 /**
- * The main entry point for the HydrousDB SDK.
+ * The root Hydrous client.
  *
- * Initialise once with your `authKey` and `securityKey`.
- * Every records and analytics call then takes a `bucketKey` option
- * so a single client instance can work across multiple buckets.
+ * Instantiate once and reuse throughout your app.
  *
  * @example
- * import { createClient } from 'hydrousdb';
+ * import { HydrousClient } from 'hydrous';
  *
- * const db = createClient({
- *   authKey:     'ak_...',   // for /auth routes
- *   securityKey: 'sk_...',   // credential for records & analytics
+ * const hydrous = new HydrousClient({
+ *   url:    'https://api.myapp.hydrous.app',
+ *   apiKey: 'hk_live_…',
  * });
- *
- * // Records — pass bucketKey on every call
- * const { data } = await db.records.get('rec_abc123', { bucketKey: 'users' });
- * await db.records.insert({ values: { name: 'Alice' } }, { bucketKey: 'users' });
- *
- * // Auth — no bucketKey needed
- * const { data, session } = await db.auth.signIn({ email: 'a@b.com', password: '...' });
- *
- * // Analytics — pass bucketKey on every call
- * const { data } = await db.analytics.count({ bucketKey: 'orders' });
  */
 declare class HydrousClient {
-    /** Record CRUD and batch operations */
-    readonly records: RecordsClient;
-    /** User authentication and session management */
+    /** Authentication — sign up, sign in, sign out, session management */
     readonly auth: AuthClient;
-    /** Analytics and aggregations */
+    /** Records — insert, select, update, delete structured data */
+    readonly records: RecordsClient;
+    /** Analytics — track events, query event history */
     readonly analytics: AnalyticsClient;
-    private readonly http;
+    /**
+     * Storage — upload, download, list, move, delete files.
+     *
+     * Every method takes a **bucket key** (`ssk_…`) as its **first argument**.
+     */
+    readonly storage: StorageClient;
     constructor(config: HydrousConfig);
 }
+
+/** 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);
+}
+declare function isHydrousError(err: unknown): err is HydrousSDKError;
+
 /**
- * Create a HydrousDB client.
+ * Create and return a `HydrousClient` instance.
  *
  * @example
- * const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+ * import { createClient } from 'hydrous';
+ *
+ * const hydrous = createClient({
+ *   url:    'https://api.myapp.hydrous.app',
+ *   apiKey: 'hk_live_…',
+ * });
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
-export { AnalyticsClient, AuthClient, HydrousClient, HydrousConfig, HydrousError, HydrousErrorBody, HydrousNetworkError, HydrousTimeoutError, RecordsClient, createClient };
+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 };