@cubis/vfsclient 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,649 @@
+/**
+ * Cache entry and adapter interfaces for isomorphic VFS caching.
+ */
+interface VFSCacheEntry {
+    data: Uint8Array;
+    contentType?: string;
+    name?: string;
+    size: number;
+    hash?: string;
+    createdAt: number;
+    expiresAt?: number;
+}
+interface VFSCacheAdapter {
+    get(key: string): Promise<VFSCacheEntry | null> | VFSCacheEntry | null;
+    set(key: string, entry: VFSCacheEntry, ttlSeconds?: number): Promise<void> | void;
+    delete(key: string): Promise<boolean> | boolean;
+    clear(): Promise<void> | void;
+    has(key: string): Promise<boolean> | boolean;
+}
+
+/**
+ * VFS Server models and response structures.
+ */
+interface AttachmentResponse {
+    id: string;
+    bucket_id: string;
+    file_id: string;
+    file_hash?: string;
+    extension: string;
+    name: string;
+    size: number;
+    type: string;
+    metadata?: Record<string, unknown>;
+    user_details?: Record<string, unknown>;
+    store?: 'local' | 's3' | 'r2' | 'vfs' | 'edge' | string;
+    is_stat_synced?: boolean;
+    created_at: string;
+    url: string;
+    key: string;
+    cdn_url?: string;
+}
+interface ObjectManifestResponse {
+    id: string;
+    bucket_id: string;
+    file_id: string;
+    file_hash?: string;
+    extension: string;
+    name: string;
+    size: number;
+    type: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    url: string;
+    key: string;
+    cdn_url?: string;
+}
+interface PreflightRequest {
+    bucket_id: string;
+    name?: string;
+    size?: number;
+    content_type?: string;
+    file_hash?: string;
+}
+interface PreflightResponse {
+    upload_protocol?: 'edge-chunks-v1' | string;
+    allowed: boolean;
+    reason?: string;
+    bucket_id: string;
+    name?: string;
+    size: number;
+    content_type?: string;
+    file_hash?: string;
+    max_upload_bytes: number;
+    remaining_bytes?: number;
+    remaining_files?: number;
+    duplicate?: AttachmentResponse;
+    upload_token?: string;
+    expires_in?: number;
+}
+interface SessionView {
+    id: string;
+    name: string;
+    state: 'receiving' | 'paused' | 'queued' | 'finalizing' | 'complete' | 'error';
+    file_hash?: string;
+    offset: number;
+    size: number;
+    chunk_size: number;
+    error?: string;
+    attempts: number;
+}
+interface BucketStat {
+    id?: string;
+    bucket_id: string;
+    total_size: number;
+    total_file: number;
+    total_files?: number;
+    total_dir?: number;
+    total_read?: number;
+    total_write?: number;
+    owner_id?: string;
+    max_size_bytes: number;
+    max_files: number;
+    lifecycle_enabled: boolean;
+    default_ttl_seconds: number;
+    created_at?: string;
+    updated_at?: string;
+}
+interface BucketStatSummary {
+    total_buckets: number;
+    total_files: number;
+    total_size: number;
+}
+interface BucketMetricsByDate {
+    date: string;
+    total_size: number;
+    total_files: number;
+}
+
+/**
+ * Problem details (RFC 7807) and SDK error definitions.
+ */
+interface ProblemDetails {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    extensions?: {
+        trace_id?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+declare class VFSError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly problem?: ProblemDetails;
+    readonly headers?: Headers;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        problem?: ProblemDetails;
+        headers?: Headers;
+        cause?: unknown;
+    });
+    /**
+     * Helper to check if error is a specific HTTP status code.
+     */
+    is(status: number): boolean;
+}
+
+type SupportedBinaryInput = Blob | File | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | NodeJS.ReadableStream | string;
+interface VFSClientOptions {
+    /**
+     * Base URL of the VFS Server (e.g. "http://localhost:5002" or "https://vfs.company.com").
+     */
+    endpoint: string;
+    /**
+     * API Key for authentication (sent via `x-api-key` header).
+     */
+    apiKey?: string;
+    /**
+     * HMAC/Hashed API Key for authentication (sent via `x-api-hash` header).
+     */
+    apiHash?: string;
+    /**
+     * Default bucket ID to use if not specified in method calls (defaults to 'default').
+     */
+    defaultBucket?: string;
+    /**
+     * Request timeout in milliseconds (default: 30,000ms = 30s).
+     */
+    timeout?: number;
+    /**
+     * Caching configuration:
+     * - `true`: automatically uses Browser Cache API in browser or FileSystem / Memory cache in Node.js
+     * - `false` or `undefined`: caching disabled
+     * - `VFSCacheAdapter`: custom cache adapter instance
+     */
+    cache?: boolean | VFSCacheAdapter;
+    /**
+     * Optional custom fetch implementation (defaults to globalThis.fetch).
+     */
+    fetch?: typeof fetch;
+    /**
+     * Enable debug logging or provide custom logger.
+     */
+    debug?: boolean | ((message: string, ...args: unknown[]) => void);
+    /**
+     * Retry configuration for transient HTTP errors (network failures, 502, 503, 504).
+     */
+    retry?: {
+        maxRetries?: number;
+        retryDelay?: number;
+        retryOnStatus?: number[];
+    };
+}
+interface UploadProgress {
+    loaded: number;
+    total: number;
+    percent: number;
+    phase: 'hashing' | 'preflight' | 'uploading' | 'chunks' | 'finalizing' | 'complete';
+}
+interface UploadInput {
+    /**
+     * File data: Blob, File, Uint8Array, Buffer, ReadableStream, or local file path in Node.js.
+     */
+    file: SupportedBinaryInput;
+    /**
+     * Target bucket ID (defaults to client's defaultBucket, or 'default').
+     */
+    bucketId?: string;
+    /**
+     * Original file name (required if input is stream/buffer without name).
+     */
+    name?: string;
+    /**
+     * MIME content type (e.g. "image/png", "application/pdf").
+     */
+    contentType?: string;
+    /**
+     * Pre-calculated SHA-256 hash. If not provided, will be computed automatically for preflight.
+     */
+    fileHash?: string;
+    /**
+     * Custom metadata attached to the file in MongoDB.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Whether to run preflight check before uploading bytes (default: true).
+     * Preflight checks quota, file size limits, and checks for deduplication.
+     */
+    preflight?: boolean;
+    /**
+     * If true, forces chunked session upload (or when preflight indicates edge-chunks-v1).
+     */
+    resumable?: boolean;
+    /**
+     * Chunk size in bytes for chunked uploads (default: 1,048,576 = 1 MiB).
+     */
+    chunkSize?: number;
+    /**
+     * Session ID to resume an interrupted chunked upload.
+     */
+    resumeId?: string;
+    /**
+     * Progress callback for upload updates.
+     */
+    onProgress?: (progress: UploadProgress) => void;
+    /**
+     * Optional AbortSignal for cancellation.
+     */
+    signal?: AbortSignal;
+}
+interface UploadMultipleInput {
+    /**
+     * List of files to upload.
+     */
+    files: UploadInput[];
+    /**
+     * Target bucket ID for all files unless overridden per file.
+     */
+    bucketId?: string;
+    /**
+     * Maximum concurrent uploads (default: 3).
+     */
+    concurrency?: number;
+    /**
+     * Overall progress callback for the batch.
+     */
+    onProgress?: (progress: {
+        totalFiles: number;
+        completedFiles: number;
+        failedFiles: number;
+        overallPercent: number;
+        currentFile?: string;
+    }) => void;
+    /**
+     * Callback on each file success.
+     */
+    onFileSuccess?: (file: UploadInput, response: AttachmentResponse) => void;
+    /**
+     * Callback on file failure.
+     */
+    onFileError?: (file: UploadInput, error: Error) => void;
+    /**
+     * AbortSignal for cancelling entire batch.
+     */
+    signal?: AbortSignal;
+}
+interface ImgProxyOptions {
+    width?: number;
+    height?: number;
+    resizingType?: 'fit' | 'fill' | 'auto';
+    format?: 'png' | 'jpeg' | 'webp' | 'avif';
+    quality?: number;
+}
+interface GetFileOptions {
+    /**
+     * Desired response format:
+     * - 'blob': Returns Blob (default in browser)
+     * - 'arrayBuffer': Returns ArrayBuffer
+     * - 'stream': Returns ReadableStream<Uint8Array>
+     * - 'text': Returns string text
+     * - 'json': Returns parsed JSON
+     */
+    responseType?: 'blob' | 'arrayBuffer' | 'stream' | 'text' | 'json';
+    /**
+     * Set Content-Disposition to attachment to force file download.
+     */
+    download?: boolean;
+    /**
+     * Whether to check and write to client cache (default: true if client cache enabled).
+     */
+    useCache?: boolean;
+    /**
+     * Optional imgproxy image transformation options.
+     */
+    imgproxy?: ImgProxyOptions;
+    /**
+     * Optional AbortSignal for cancelling download.
+     */
+    signal?: AbortSignal;
+}
+interface GetUrlOptions {
+    /**
+     * Set download=true query param.
+     */
+    download?: boolean;
+    /**
+     * Optional imgproxy transformation query params.
+     */
+    imgproxy?: ImgProxyOptions;
+}
+interface ListFilesOptions {
+    /**
+     * Target bucket ID (defaults to defaultBucket).
+     */
+    bucketId?: string;
+    /**
+     * Optional AbortSignal.
+     */
+    signal?: AbortSignal;
+}
+interface BucketStatsListResponse {
+    items: BucketStat[];
+    total?: number;
+}
+
+interface RequestOptions {
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | boolean | undefined | null>;
+    body?: BodyInit | null;
+    timeout?: number;
+    signal?: AbortSignal;
+    skipAuth?: boolean;
+}
+interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    totalCount?: number;
+}
+declare class HttpClient {
+    private readonly endpoint;
+    private readonly apiKey?;
+    private readonly apiHash?;
+    private readonly defaultTimeout;
+    private readonly fetchImpl;
+    private readonly debug?;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly retryOnStatus;
+    constructor(options: VFSClientOptions);
+    getEndpoint(): string;
+    getApiKey(): string | undefined;
+    getApiHash(): string | undefined;
+    private buildUrl;
+    private buildHeaders;
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    post<T = unknown>(path: string, body?: BodyInit | null, options?: RequestOptions): Promise<HttpResponse<T>>;
+    put<T = unknown>(path: string, body?: BodyInit | null, options?: RequestOptions): Promise<HttpResponse<T>>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Fetches raw Response object directly (useful for streaming file downloads).
+     */
+    fetchRaw(path: string, options?: RequestOptions): Promise<Response>;
+}
+
+interface QueueItem {
+    id: string;
+    input: UploadInput;
+    status: 'pending' | 'uploading' | 'completed' | 'failed' | 'cancelled';
+    progress: number;
+    response?: AttachmentResponse;
+    error?: Error;
+}
+interface QueueProgress {
+    totalFiles: number;
+    completedFiles: number;
+    failedFiles: number;
+    overallPercent: number;
+    currentFile?: string;
+}
+type QueueListener = (progress: QueueProgress, item?: QueueItem) => void;
+declare class BackgroundUploadQueue {
+    private readonly http;
+    private readonly defaultBucket;
+    private concurrency;
+    private items;
+    private activeCount;
+    private isPaused;
+    private abortController;
+    private listeners;
+    private onFileSuccessCb?;
+    private onFileErrorCb?;
+    private onCompletePromiseResolve?;
+    private onCompletePromiseReject?;
+    constructor(http: HttpClient, options?: {
+        defaultBucket?: string;
+        concurrency?: number;
+    });
+    onProgress(listener: QueueListener): () => void;
+    onFileSuccess(cb: (file: UploadInput, response: AttachmentResponse) => void): this;
+    onFileError(cb: (file: UploadInput, error: Error) => void): this;
+    add(input: UploadInput): string;
+    addAll(inputs: UploadInput[]): string[];
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    clear(): void;
+    getItems(): ReadonlyArray<QueueItem>;
+    getProgress(): QueueProgress;
+    private notifyProgress;
+    private processQueue;
+    private uploadItem;
+    private checkCompletion;
+    /**
+     * Returns a promise that resolves when all items currently in the queue have completed.
+     */
+    wait(): Promise<AttachmentResponse[]>;
+}
+/**
+ * Uploads multiple files with concurrency control and progress tracking.
+ */
+declare function uploadMultipleFiles(http: HttpClient, input: UploadMultipleInput, defaultBucket?: string): Promise<AttachmentResponse[]>;
+
+declare class VFSClient {
+    readonly http: HttpClient;
+    readonly defaultBucket: string;
+    readonly cache?: VFSCacheAdapter;
+    constructor(options: VFSClientOptions);
+    /**
+     * Upload a single file to VFS.
+     * Proactively checks preflight quota and deduplication: if identical file content exists,
+     * skips transfer and returns the existing file immediately.
+     */
+    upload(input: UploadInput): Promise<AttachmentResponse>;
+    /**
+     * Upload multiple files with concurrency control, progress reporting, and stream/chunk support.
+     */
+    uploadMultiple(input: UploadMultipleInput): Promise<AttachmentResponse[]>;
+    /**
+     * Creates a background upload queue manager for continuous uploads with pause/resume and events.
+     */
+    createBackgroundQueue(options?: {
+        concurrency?: number;
+        bucketId?: string;
+    }): BackgroundUploadQueue;
+    /**
+     * Retrieves a file from VFS with multi-tier caching (Browser CacheStorage / Server Filesystem).
+     */
+    getFile(bucketId: string, fileId: string, options?: GetFileOptions): Promise<Blob | ArrayBuffer | ReadableStream<Uint8Array> | string | unknown>;
+    /**
+     * Retrieves a file directly by its SHA-256 hash (/h/:hash).
+     * Hash-addressed content is immutable and cached indefinitely.
+     */
+    getFileByHash(hash: string, options?: GetFileOptions): Promise<Blob | ArrayBuffer | ReadableStream<Uint8Array> | string | unknown>;
+    /**
+     * Gets metadata manifest of an uploaded file as a JSON object without downloading the file data.
+     */
+    getFileMetadata(bucketId: string, fileId: string, signal?: AbortSignal): Promise<ObjectManifestResponse>;
+    /**
+     * Gets metadata manifest of a file by its SHA-256 hash.
+     */
+    getFileMetadataByHash(hash: string, signal?: AbortSignal): Promise<ObjectManifestResponse>;
+    /**
+     * Generates public/access URL for a file, supporting imgproxy transformations and download triggers.
+     */
+    getFileUrl(bucketId: string, fileId: string, options?: GetUrlOptions): string;
+    /**
+     * Generates public URL for a file addressed by its SHA-256 hash.
+     */
+    getFileUrlByHash(hash: string): string;
+    /**
+     * Deletes a file by bucket ID and file ID, invalidating any cached copies.
+     */
+    deleteFile(bucketId: string, fileId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Deletes a file record by catalog ID.
+     */
+    deleteFileById(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Deletes all files within a specified bucket.
+     */
+    deleteAllInBucket(bucketId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Lists stored objects in a bucket.
+     */
+    listFiles(options?: ListFilesOptions): Promise<AttachmentResponse[]>;
+    /**
+     * Gets real-time statistics for a bucket (total files, storage usage, read/write counts, quota limits).
+     */
+    getBucketStats(bucketId?: string, signal?: AbortSignal): Promise<BucketStat>;
+    /**
+     * Gets a list of all bucket statistics.
+     */
+    getAllBucketStats(params?: {
+        page?: number;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<BucketStatsListResponse>;
+    /**
+     * Gets overall system summary of bucket statistics (total buckets, total files, total storage size).
+     */
+    getBucketSummary(signal?: AbortSignal): Promise<BucketStatSummary>;
+    /**
+     * Gets date-based usage growth metrics for a bucket.
+     */
+    getBucketMetrics(bucketId?: string, signal?: AbortSignal): Promise<BucketMetricsByDate[]>;
+}
+
+interface MemoryCacheOptions {
+    /**
+     * Maximum number of items in cache (default: 200).
+     */
+    maxItems?: number;
+    /**
+     * Default TTL in seconds (default: 3600 = 1 hour, 0 for indefinite).
+     */
+    defaultTTL?: number;
+}
+declare class MemoryCacheAdapter implements VFSCacheAdapter {
+    private readonly store;
+    private readonly maxItems;
+    private readonly defaultTTL;
+    constructor(options?: MemoryCacheOptions);
+    private isExpired;
+    get(key: string): VFSCacheEntry | null;
+    set(key: string, entry: VFSCacheEntry, ttlSeconds?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    has(key: string): boolean;
+    size(): number;
+}
+
+interface BrowserCacheOptions {
+    cacheName?: string;
+    defaultTTL?: number;
+}
+declare class BrowserCacheAdapter implements VFSCacheAdapter {
+    private readonly cacheName;
+    private readonly defaultTTL;
+    private readonly fallback;
+    constructor(options?: BrowserCacheOptions);
+    private isAvailable;
+    private urlForKey;
+    get(key: string): Promise<VFSCacheEntry | null>;
+    set(key: string, entry: VFSCacheEntry, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+
+interface FileSystemCacheOptions {
+    /**
+     * Directory to store cached files (default: "./.vfs-cache").
+     */
+    cacheDir?: string;
+    /**
+     * Default TTL in seconds (default: 3600 = 1 hour).
+     */
+    defaultTTL?: number;
+}
+declare class FileSystemCacheAdapter implements VFSCacheAdapter {
+    private readonly cacheDir;
+    private readonly defaultTTL;
+    private readonly fallback;
+    private isNodeEnv;
+    constructor(options?: FileSystemCacheOptions);
+    private sanitizeKey;
+    private getFs;
+    private ensureDir;
+    get(key: string): Promise<VFSCacheEntry | null>;
+    set(key: string, entry: VFSCacheEntry, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+
+/**
+ * Creates the most suitable cache adapter for the current runtime environment.
+ * - In Browser: Uses BrowserCacheAdapter (CacheStorage / IndexedDB / Memory fallback)
+ * - In Node.js / Bun: Uses FileSystemCacheAdapter (or MemoryCacheAdapter if directory unwritable)
+ * - Otherwise: Uses MemoryCacheAdapter
+ */
+declare function createDefaultCache(): VFSCacheAdapter;
+
+declare function uploadSingleFile(http: HttpClient, input: UploadInput, defaultBucket?: string): Promise<AttachmentResponse>;
+
+/**
+ * Uploads a file using the VFS Resumable Chunked Session Upload Protocol.
+ * Ideal for large files, unstable connections, and edge-distributed storage.
+ */
+declare function uploadSessionFile(http: HttpClient, input: UploadInput, defaultBucket?: string): Promise<AttachmentResponse>;
+
+/**
+ * Checks metadata with VFS Server preflight endpoint before uploading data.
+ * Detects quota violations, file size exceedance, and duplicate hits.
+ */
+declare function executePreflight(http: HttpClient, req: PreflightRequest, signal?: AbortSignal): Promise<PreflightResponse>;
+
+interface NormalizedFileInput {
+    bytes: Uint8Array;
+    name: string;
+    size: number;
+    contentType: string;
+    hash: string;
+}
+/**
+ * Detects basic mime type from file name extension.
+ */
+declare function guessContentType(filename: string): string;
+/**
+ * Normalizes any supported input into an in-memory Uint8Array with metadata and SHA-256 hash.
+ */
+declare function normalizeUploadInput(input: UploadInput): Promise<NormalizedFileInput>;
+
+/**
+ * Calculates SHA-256 hex digest of an ArrayBuffer or Uint8Array.
+ */
+declare function calculateSHA256(data: ArrayBuffer | Uint8Array | string): Promise<string>;
+/**
+ * Calculates SHA-256 of a Blob or File.
+ */
+declare function calculateBlobSHA256(blob: Blob): Promise<string>;
+
+export { type AttachmentResponse, BackgroundUploadQueue, BrowserCacheAdapter, type BrowserCacheOptions, type BucketMetricsByDate, type BucketStat, type BucketStatSummary, type BucketStatsListResponse, FileSystemCacheAdapter, type FileSystemCacheOptions, type GetFileOptions, type GetUrlOptions, HttpClient, type ImgProxyOptions, type ListFilesOptions, MemoryCacheAdapter, type MemoryCacheOptions, type ObjectManifestResponse, type PreflightRequest, type PreflightResponse, type ProblemDetails, type QueueItem, type QueueListener, type QueueProgress, type SessionView, type SupportedBinaryInput, type UploadInput, type UploadMultipleInput, type UploadProgress, type VFSCacheAdapter, type VFSCacheEntry, VFSClient, type VFSClientOptions, VFSError, calculateBlobSHA256, calculateSHA256, createDefaultCache, executePreflight, guessContentType, normalizeUploadInput, uploadMultipleFiles, uploadSessionFile, uploadSingleFile };