hydrousdb 2.0.0 → 2.0.3

package/dist/index.d.ts

@@ -1,79 +1,554 @@
-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';
-
 /**
- * Thrown for any non-2xx response from the HydrousDB API.
+ * Named storage keys.
+ * Create as many as you need in the HydrousDB dashboard and give each one a
+ * meaningful name — you'll reference it by name when calling storage methods.
+ *
+ * @example
+ * {
+ *   main:      'ssk_main_…',
+ *   avatars:   'ssk_avatars_…',
+ *   documents: 'ssk_docs_…',
+ * }
  */
-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);
+type StorageKeys = Record<string, string>;
+interface HydrousConfig {
+    /** Your HydrousDB project base URL */
+    url: string;
+    /** Auth service key — used for all auth.* operations */
+    authKey: string;
+    /** Bucket security key — used for records.* and analytics.* operations */
+    bucketSecurityKey: string;
+    /**
+     * Storage keys object.  Each property name is a label you choose; each
+     * value is a storage key (ssk_…) from your dashboard.
+     * You can have as many as you need.
+     */
+    storageKeys: StorageKeys;
+    /** Optional global request timeout in milliseconds (default: 30 000) */
+    timeout?: number;
 }
-/**
- * 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);
+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;
 }
+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;
+    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 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;
+}
+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 ListOptions {
+    /** Folder prefix to list (empty = bucket root) */
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface SignedUrlOptions {
+    /** How long the URL stays valid in seconds (default: 3600) */
+    expiresIn?: number;
+}
+
+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;
+}
+
+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>>;
+}
+
+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>>;
+}
+
 /**
- * Thrown when a request exceeds the configured timeout.
+ * A storage client that is already bound to a specific storage key.
+ * You get one of these by calling  `db.storage('keyName')`.
+ *
+ * None of the methods on this class require you to pass a bucket key —
+ * it's already baked in.
  */
-declare class HydrousTimeoutError extends Error {
-    constructor(timeoutMs: number);
+declare class ScopedStorageClient {
+    private readonly base;
+    private readonly key;
+    readonly keyName: string;
+    constructor(baseUrl: string, keyName: string, bucketKey: string);
+    /**
+     * Upload a single file.
+     *
+     * Supply `onProgress` to receive live upload ticks including bytes
+     * transferred, speed (bytes/sec), ETA, and lifecycle stage.
+     *
+     * **Stage sequence:**
+     * `pending → compressing → uploading → done | error`
+     *
+     * In browsers the progress is tracked at the network level via XHR, so
+     * `percent` reflects actual bytes leaving the device.  `done` only fires
+     * after the server confirms the write to cloud storage, so 100% is real.
+     *
+     * @example
+     * 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`);
+     *   },
+     * });
+     */
+    upload(file: File | Blob | Uint8Array | ArrayBuffer, options?: UploadOptions): Promise<HydrousResponse<UploadResult>>;
+    /**
+     * Upload raw text or JSON content directly — no File object needed.
+     *
+     * @example
+     * // Save a JSON config
+     * await db.storage('configs').uploadText(
+     *   'settings/app.json',
+     *   JSON.stringify({ theme: 'dark' }),
+     *   { mimeType: 'application/json' }
+     * );
+     */
+    uploadText(path: string, content: string, options?: {
+        mimeType?: string;
+        overwrite?: boolean;
+        onProgress?: UploadOptions['onProgress'];
+    }): Promise<HydrousResponse<UploadResult>>;
+    /**
+     * Upload multiple files in one request.
+     *
+     * `onProgress` fires per file — use `p.index` to identify which file.
+     * All files receive a `pending` event upfront so you can render progress
+     * bars immediately before any data is sent.
+     *
+     * @example
+     * await db.storage('documents').batchUpload(files, {
+     *   prefix:     'reports/2024/',
+     *   onProgress: (p) => updateBar(p.index, p.percent),
+     * });
+     */
+    batchUpload(files: File[], options?: BatchUploadOptions): Promise<HydrousResponse<BatchUploadResult>>;
+    /**
+     * Download a single file and return its content as an `ArrayBuffer`.
+     *
+     * @example
+     * const { data } = await db.storage('avatars').download('users/alice.jpg');
+     * const blob = new Blob([data!]);
+     * img.src = URL.createObjectURL(blob);
+     */
+    download(filePath: string): Promise<HydrousResponse<ArrayBuffer>>;
+    /**
+     * Download multiple files in one request.
+     *
+     * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
+     *
+     * @example
+     * const { data } = await db.storage('reports').batchDownload(
+     *   ['jan.pdf', 'feb.pdf'],
+     *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
+     * );
+     */
+    batchDownload(filePaths: string[], options?: BatchDownloadOptions): Promise<HydrousResponse<BatchDownloadFile[]>>;
+    /**
+     * List files and folders (paginated).
+     *
+     * @example
+     * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
+     * for (const item of data!.items) {
+     *   console.log(item.type, item.path, item.size);
+     * }
+     */
+    list(options?: ListOptions): Promise<HydrousResponse<ListResult>>;
+    /**
+     * Get metadata for a file (size, MIME type, compression, etc.)
+     *
+     * @example
+     * const { data: meta } = await db.storage('docs').metadata('report.pdf');
+     * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
+     */
+    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>>;
+    /**
+     * Generate a time-limited public URL for a private file.
+     *
+     * @example
+     * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
+     * console.log(data!.signedUrl); // share this
+     */
+    signedUrl(filePath: string, options?: SignedUrlOptions): Promise<HydrousResponse<SignedUrlResult>>;
+    /**
+     * Get usage and billing stats for this storage key.
+     *
+     * @example
+     * const { data } = await db.storage('main').stats();
+     * console.log(data!.totalFiles, data!.totalSizeBytes);
+     */
+    stats(): Promise<HydrousResponse<StorageStats>>;
 }
 
+interface CallableStorage {
+    /** Get a scoped storage client by key name */
+    (keyName: string): ScopedStorageClient;
+    /** Same as calling db.storage(keyName) — more explicit */
+    use(keyName: string): ScopedStorageClient;
+    /** Return names of all configured storage keys */
+    keyNames(): string[];
+}
 /**
- * The main entry point for the HydrousDB SDK.
+ * The HydrousDB root 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.
+ * Create once and reuse across your app:
  *
- * @example
+ * ```ts
  * import { createClient } from 'hydrousdb';
  *
  * const db = createClient({
- *   authKey:     'ak_...',   // for /auth routes
- *   securityKey: 'sk_...',   // credential for records & analytics
+ *   url:               'https://api.myapp.hydrous.app',
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     documents: 'ssk_docs_…',
+ *   },
  * });
- *
- * // 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 */
+    /** Auth — 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 and query history */
     readonly analytics: AnalyticsClient;
-    private readonly http;
+    /**
+     * Storage — call with the name of the key you want.
+     *
+     * ```ts
+     * db.storage('avatars').upload(file, { path: 'user.jpg' })
+     * db.storage('documents').list({ prefix: 'invoices/' })
+     * db.storage('main').stats()
+     * ```
+     */
+    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);
+    /**
+     * Get a storage client scoped to a named key.
+     *
+     * @param keyName - Must match a property you declared in `storageKeys`
+     *
+     * @example
+     * const avatarStore   = db.storage('avatars');
+     * const documentStore = db.storage('documents');
+     *
+     * await avatarStore.upload(file, { path: 'users/alice.jpg' });
+     * const list = await documentStore.list({ prefix: 'invoices/' });
+     */
+    use(keyName: string): ScopedStorageClient;
+    /** Return the names of all configured storage keys */
+    keyNames(): string[];
 }
+
+declare const eq: (field: string, value: unknown) => Filter;
+declare const neq: (field: string, value: unknown) => Filter;
+declare const gt: (field: string, value: unknown) => Filter;
+declare const lt: (field: string, value: unknown) => Filter;
+declare const gte: (field: string, value: unknown) => Filter;
+declare const lte: (field: string, value: unknown) => Filter;
+declare const inArray: (field: string, value: unknown[]) => Filter;
+
+declare class HydrousDBError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(message: string, code?: string, status?: number);
+}
+declare function isHydrousError(err: unknown): err is HydrousDBError;
+
 /**
  * Create a HydrousDB client.
  *
  * @example
- * const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+ * import { createClient } from 'hydrousdb';
+ *
+ * const db = createClient({
+ *   url:               'https://api.myapp.hydrous.app',
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     documents: 'ssk_docs_…',
+ *   },
+ * });
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
-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 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 };