hydrousdb 2.0.3 → 3.0.1

package/dist/index.d.cts

@@ -0,0 +1,1080 @@
+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>;
+}
+
+/**
+ * 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 {
+    /**
+     * 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 (starts with `hk_bucket_`).
+     * Used for all `/records/*` and `/analytics/*` routes.
+     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
+     */
+    bucketSecurityKey: string;
+    /**
+     * 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;
+    /**
+     * Override the API base URL. Defaults to the official HydrousDB endpoint.
+     * You almost never need to set this.
+     */
+    baseUrl?: string;
+}
+interface SignupOptions {
+    email: string;
+    password: string;
+    fullName?: string;
+    [key: string]: unknown;
+}
+interface LoginOptions {
+    email: string;
+    password: string;
+}
+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 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;
+}
+interface ListUsersResult {
+    users: UserRecord[];
+    total: 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;
+    /** TTL in seconds for the signed upload URL (default 900 = 15 min). */
+    expiresInSeconds?: number;
+}
+interface UploadResult {
+    path: string;
+    mimeType: string;
+    size: number;
+    isPublic: boolean;
+    publicUrl: string | null;
+    downloadUrl: string | null;
+}
+interface UploadUrlResult {
+    uploadUrl: string;
+    path: string;
+    mimeType: string;
+    expiresAt: string;
+    expiresIn: number;
+}
+interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+    recursive?: boolean;
+}
+interface FileEntry {
+    name: string;
+    path: string;
+    size?: number;
+    mimeType?: string;
+    isPublic?: boolean;
+    publicUrl?: string | null;
+    downloadUrl?: string | null;
+    updatedAt?: string;
+}
+interface ListResult {
+    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;
+    expiresAt: string;
+    expiresIn: number;
+    path: string;
+}
+interface StorageStats {
+    totalFiles: number;
+    totalBytes: number;
+    uploadCount: number;
+    downloadCount: number;
+    deleteCount: number;
+}
+interface BatchUploadItem {
+    path: string;
+    mimeType: string;
+    size: number;
+    isPublic?: boolean;
+    overwrite?: boolean;
+}
+interface BatchUploadUrlResult {
+    files: Array<UploadUrlResult & {
+        index: number;
+    }>;
+}
+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.
+ * 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 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>;
+}
+
+/**
+ * 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 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>>;
+}
+
+/**
+ * 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`.
+ *
+ * @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 StorageManager {
+    private readonly http;
+    private readonly storageKey;
+    private readonly basePath;
+    constructor(http: HttpClient, storageKey: string);
+    /** Headers for all storage requests — uses X-Storage-Key, not X-Api-Key. */
+    private get authHeaders();
+    /**
+     * Upload a file to storage in one step (server-buffered, up to 500 MB).
+     * For files >10 MB or when you need upload progress, use `getUploadUrl()` instead.
+     *
+     * @param data     File data as a Blob, Buffer, Uint8Array, or ArrayBuffer.
+     * @param path     Destination path in your storage (e.g. `"avatars/alice.jpg"`).
+     * @param options  Upload options: isPublic, overwrite, mimeType.
+     *
+     * @example
+     * ```ts
+     * // Upload a public avatar
+     * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+     * console.log(result.publicUrl); // → https://...
+     *
+     * // Upload a private document
+     * const result = await storage.upload(pdfBuffer, 'docs/contract.pdf');
+     * console.log(result.downloadUrl); // → /storage/download/docs/contract.pdf
+     * ```
+     */
+    upload(data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Upload raw JSON or plain text data as a file.
+     *
+     * @example
+     * ```ts
+     * const result = await storage.uploadRaw(
+     *   { config: { theme: 'dark' } },
+     *   'settings/user-config.json',
+     *   { isPublic: false },
+     * );
+     * ```
+     */
+    uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Step 1 of the recommended upload flow.
+     * Get a signed URL to upload directly to GCS from the client (supports progress).
+     *
+     * @example
+     * ```ts
+     * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
+     *   path: 'videos/intro.mp4',
+     *   mimeType: 'video/mp4',
+     *   size: file.size,
+     *   isPublic: true,
+     * });
+     *
+     * // Upload using XHR for progress tracking
+     * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (pct) => {
+     *   console.log(`${pct}% uploaded`);
+     * });
+     *
+     * // Step 3: confirm
+     * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
+     * ```
+     */
+    getUploadUrl(opts: {
+        path: string;
+        mimeType: string;
+        size: number;
+        isPublic?: boolean;
+        overwrite?: boolean;
+        expiresInSeconds?: number;
+    }): Promise<UploadUrlResult>;
+    /**
+     * Upload data directly to a signed GCS URL (no auth headers needed).
+     * Optionally tracks progress via a callback.
+     *
+     * @param signedUrl  The URL returned by `getUploadUrl()`.
+     * @param data       File data.
+     * @param mimeType   Must match what was used in `getUploadUrl()`.
+     * @param onProgress Optional callback called with 0–100 progress percentage.
+     */
+    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
+    /**
+     * Step 3 of the recommended upload flow.
+     * Confirm a direct upload and register metadata on the server.
+     *
+     * @example
+     * ```ts
+     * const result = await storage.confirmUpload({
+     *   path: 'videos/intro.mp4',
+     *   mimeType: 'video/mp4',
+     *   isPublic: true,
+     * });
+     * console.log(result.publicUrl);
+     * ```
+     */
+    confirmUpload(opts: {
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }): Promise<UploadResult>;
+    /**
+     * Get signed upload URLs for multiple files at once.
+     *
+     * @example
+     * ```ts
+     * const { files } = await storage.getBatchUploadUrls([
+     *   { path: 'images/photo1.jpg', mimeType: 'image/jpeg', size: 204800 },
+     *   { path: 'images/photo2.jpg', mimeType: 'image/jpeg', size: 153600 },
+     * ]);
+     *
+     * // Upload each file and confirm
+     * for (const f of files) {
+     *   await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
+     *   await storage.confirmUpload({ path: f.path, mimeType: f.mimeType });
+     * }
+     * ```
+     */
+    getBatchUploadUrls(files: BatchUploadItem[]): Promise<BatchUploadUrlResult>;
+    /**
+     * Confirm multiple direct uploads at once.
+     */
+    batchConfirmUploads(items: Array<{
+        path: string;
+        mimeType: string;
+        isPublic?: boolean;
+    }>): Promise<UploadResult[]>;
+    /**
+     * Download a private file as an ArrayBuffer.
+     * For public files, use the `publicUrl` directly — no SDK needed.
+     *
+     * @example
+     * ```ts
+     * const buffer = await storage.download('docs/contract.pdf');
+     * const blob = new Blob([buffer], { type: 'application/pdf' });
+     * // Open in browser:
+     * window.open(URL.createObjectURL(blob));
+     * ```
+     */
+    download(path: string): Promise<ArrayBuffer>;
+    /**
+     * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+     *
+     * @example
+     * ```ts
+     * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+     * ```
+     */
+    batchDownload(paths: string[]): Promise<Record<string, string>>;
+    /**
+     * List files and folders at a given path prefix.
+     *
+     * @example
+     * ```ts
+     * // List everything in the root
+     * const { files, folders } = await storage.list();
+     *
+     * // List a specific folder
+     * const { files, folders, hasMore, nextCursor } = await storage.list({
+     *   prefix: 'avatars/',
+     *   limit: 20,
+     * });
+     *
+     * // Next page
+     * const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
+     * ```
+     */
+    list(opts?: ListOptions): Promise<ListResult>;
+    /**
+     * Get metadata for a file (size, MIME type, visibility, URLs).
+     *
+     * @example
+     * ```ts
+     * const meta = await storage.getMetadata('avatars/alice.jpg');
+     * console.log(meta.size, meta.isPublic, meta.publicUrl);
+     * ```
+     */
+    getMetadata(path: string): Promise<FileMetadata>;
+    /**
+     * Generate a time-limited download URL for a private file.
+     * The URL can be shared externally without requiring an `X-Storage-Key`.
+     *
+     * > **Note:** Downloads via signed URLs bypass the server, so download stats
+     * > are NOT tracked. Use `downloadUrl` for tracked downloads.
+     *
+     * @param path       Path to the file.
+     * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+     *
+     * @example
+     * ```ts
+     * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
+     * // Share signedUrl with the recipient — it expires in 30 minutes.
+     * ```
+     */
+    getSignedUrl(path: string, expiresIn?: number): Promise<SignedUrlResult>;
+    /**
+     * Change a file's visibility between public and private after upload.
+     *
+     * @example
+     * ```ts
+     * // Make a file public
+     * const result = await storage.setVisibility('avatars/alice.jpg', true);
+     * console.log(result.publicUrl); // CDN URL
+     *
+     * // Make a file private
+     * const result = await storage.setVisibility('avatars/alice.jpg', false);
+     * console.log(result.downloadUrl); // Auth-required URL
+     * ```
+     */
+    setVisibility(path: string, isPublic: boolean): Promise<{
+        path: string;
+        isPublic: boolean;
+        publicUrl: string | null;
+        downloadUrl: string | null;
+    }>;
+    /**
+     * Create a folder (a GCS prefix placeholder).
+     *
+     * @example
+     * ```ts
+     * await storage.createFolder('uploads/2025/');
+     * ```
+     */
+    createFolder(path: string): Promise<{
+        path: string;
+    }>;
+    /**
+     * Delete a single file.
+     *
+     * @example
+     * ```ts
+     * await storage.deleteFile('avatars/old-avatar.jpg');
+     * ```
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * Delete a folder and all its contents recursively.
+     *
+     * @example
+     * ```ts
+     * await storage.deleteFolder('temp/');
+     * ```
+     */
+    deleteFolder(path: string): Promise<void>;
+    /**
+     * Move or rename a file.
+     *
+     * @example
+     * ```ts
+     * // Rename
+     * await storage.move('docs/draft.pdf', 'docs/final.pdf');
+     * // Move to a different folder
+     * await storage.move('inbox/report.xlsx', 'archive/2025/report.xlsx');
+     * ```
+     */
+    move(from: string, to: string): Promise<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Copy a file to a new path.
+     *
+     * @example
+     * ```ts
+     * await storage.copy('templates/base.html', 'sites/my-site/index.html');
+     * ```
+     */
+    copy(from: string, to: string): Promise<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Get storage statistics for your key: total files, bytes, operation counts.
+     *
+     * @example
+     * ```ts
+     * const stats = await storage.getStats();
+     * console.log(`${stats.totalFiles} files, ${(stats.totalBytes / 1e6).toFixed(1)} MB`);
+     * ```
+     */
+    getStats(): Promise<StorageStats>;
+    /**
+     * Ping the storage service. No authentication required.
+     *
+     * @example
+     * ```ts
+     * const info = await storage.info();
+     * // → { ok: true, storageRoot: 'hydrous-storage' }
+     * ```
+     */
+    info(): Promise<{
+        ok: boolean;
+        storageRoot: string;
+    }>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * HydrousClient — the main entry point for the HydrousDB SDK.
+ *
+ * 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({
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     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 {
+    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);
+    /**
+     * Get a typed records client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
+     *
+     * @example
+     * ```ts
+     * interface Post { title: string; published: boolean }
+     * const posts = db.records<Post>('blog-posts');
+     * const post = await posts.create({ title: 'Hello', published: false });
+     * ```
+     */
+    records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
+    /**
+     * Get an auth client for the named user bucket.
+     * 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 an analytics client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
+     *
+     * @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
+     * ```ts
+     * const avatars   = db.storage('avatars');
+     * const documents = db.storage('documents');
+     *
+     * // Upload to avatars bucket
+     * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
+     *
+     * // Scope to a sub-folder
+     * const userDocs = db.storage('documents').scope(`users/${userId}`);
+     * await userDocs.upload(pdfBuffer, 'contract.pdf');
+     * ```
+     */
+    storage(keyName: string): StorageManager & {
+        scope: (prefix: string) => ScopedStorage;
+    };
+}
+/**
+ * Create a new HydrousDB client.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'hydrousdb';
+ *
+ * const db = createClient({
+ *   authKey:           process.env.HYDROUS_AUTH_KEY!,
+ *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+ *   storageKeys: {
+ *     main:      process.env.HYDROUS_STORAGE_MAIN!,
+ *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+ *     documents: process.env.HYDROUS_STORAGE_DOCS!,
+ *   },
+ * });
+ * ```
+ */
+declare function createClient(config: HydrousConfig): HydrousClient;
+
+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 };