@mountra/mountra-sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,353 @@
+/**
+ * Per-download cache behavior, modelled on `RequestInit.cache`:
+ * - `default`: serve a fresh cached file without contacting Mountra; otherwise
+ *   export it and reuse any cached chunks.
+ * - `no-cache`: always export first, but still reuse cached chunks.
+ * - `no-store`: neither read from nor write to the cache.
+ */
+type DownloadCacheMode = "default" | "no-cache" | "no-store";
+interface DownloadCacheOptions {
+    /** Upper bound of cached chunk bytes, shared by all workspaces. Defaults to 512 MiB. */
+    maxBytes?: number;
+    /**
+     * Chunks larger than this are never cached, because a downloaded chunk is
+     * buffered in memory before it is stored. Defaults to 128 MiB and never
+     * exceeds `maxBytes`.
+     */
+    maxChunkBytes?: number;
+    /**
+     * How long a downloaded file may be served from the cache without asking
+     * Mountra whether it changed. Defaults to 5 minutes; 0 always revalidates.
+     */
+    ttlMs?: number;
+    /** Cache storage. Defaults to IndexedDB, or memory when IndexedDB is unavailable. */
+    store?: DownloadCacheStore;
+}
+interface DownloadCacheChunk {
+    index: number;
+    offset: number;
+    size: number;
+    storageKey: string;
+}
+/** The chunk layout of one file. Signed URLs are never cached. */
+interface DownloadCacheFile {
+    path: string;
+    size: number;
+    contentType?: string;
+    chunks: DownloadCacheChunk[];
+    /** When Mountra last confirmed this layout. */
+    cachedAt: number;
+    /** After this time the layout must be confirmed by Mountra again. */
+    expiresAt: number;
+}
+interface DownloadCacheUsage {
+    bytes: number;
+    chunks: number;
+}
+/**
+ * Storage behind the download cache. Every entry is scoped by an opaque
+ * workspace key, so one workspace never observes another workspace's entries.
+ */
+interface DownloadCacheStore {
+    getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
+    putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
+    removeFile(workspace: string, fileKey: string): Promise<void>;
+    /** Return the chunk bytes and mark the chunk as most recently used. */
+    getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
+    /** Store the chunk bytes, then evict least recently used chunks until at most `maxBytes` remain. */
+    putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
+    /** Remove every entry, or only the entries of one workspace. */
+    clear(workspace?: string): Promise<void>;
+    usage(workspace?: string): Promise<DownloadCacheUsage>;
+}
+declare class InMemoryDownloadCacheStore implements DownloadCacheStore {
+    private readonly files;
+    /** Map iteration order is the LRU order: the first entry is the least recently used. */
+    private readonly chunks;
+    private bytes;
+    getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
+    putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
+    removeFile(workspace: string, fileKey: string): Promise<void>;
+    getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
+    putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+    usage(workspace?: string): Promise<DownloadCacheUsage>;
+    private removeChunk;
+}
+interface IndexedDBDownloadCacheStoreOptions {
+    /** Use a separate database, for example one per signed-in user. */
+    databaseName?: string;
+}
+declare class IndexedDBDownloadCacheStore implements DownloadCacheStore {
+    private readonly databaseName;
+    private readonly fallback;
+    private databasePromise?;
+    constructor(options?: IndexedDBDownloadCacheStoreOptions);
+    getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
+    putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
+    removeFile(workspace: string, fileKey: string): Promise<void>;
+    getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
+    putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+    usage(workspace?: string): Promise<DownloadCacheUsage>;
+    private openDatabase;
+}
+/** Cache policy of one client. Cache failures degrade to misses and never fail a download. */
+declare class DownloadCache {
+    readonly maxBytes: number;
+    readonly maxChunkBytes: number;
+    readonly ttlMs: number;
+    private readonly store;
+    constructor(options: DownloadCacheOptions);
+    /** Return a file that has not expired together with all of its chunk bytes. */
+    loadFile(workspace: string, fileKey: string): Promise<{
+        file: DownloadCacheFile;
+        chunks: Map<number, Blob>;
+    } | null>;
+    readChunk(workspace: string, chunk: DownloadCacheChunk): Promise<Blob | null>;
+    canStoreChunk(chunk: DownloadCacheChunk): boolean;
+    /** Returns whether the chunk is now cached. */
+    storeChunk(workspace: string, chunk: DownloadCacheChunk, data: Blob): Promise<boolean>;
+    storeFile(workspace: string, fileKey: string, file: Omit<DownloadCacheFile, "cachedAt" | "expiresAt">): Promise<void>;
+    invalidateFiles(workspace: string, fileKeys: string[]): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+    usage(workspace?: string): Promise<DownloadCacheUsage>;
+}
+
+interface FileSystemWritableFileStreamLike {
+    write(data: Uint8Array | Blob): Promise<void>;
+    seek(position: number): Promise<void>;
+    truncate(size: number): Promise<void>;
+    close(): Promise<void>;
+    abort?(): Promise<void>;
+}
+interface FileSystemFileHandleLike {
+    readonly kind?: "file";
+    readonly name?: string;
+    createWritable(options?: {
+        keepExistingData?: boolean;
+    }): Promise<FileSystemWritableFileStreamLike>;
+    isSameEntry?(other: FileSystemFileHandleLike): Promise<boolean>;
+    queryPermission?(descriptor?: {
+        mode?: "read" | "readwrite";
+    }): Promise<PermissionState>;
+    requestPermission?(descriptor?: {
+        mode?: "read" | "readwrite";
+    }): Promise<PermissionState>;
+}
+interface ExportFileOptions extends WorkspaceSelector {
+    path?: string;
+    ino?: number | string;
+    timeout?: number;
+    contentDisposition?: string;
+    downloadFilename?: string;
+    signal?: AbortSignal;
+}
+interface ExportFileChunk {
+    index: number;
+    offset: number;
+    size: number;
+    storageKey: string;
+    url: string;
+}
+interface ExportFileResponse {
+    path: string;
+    storageKey: string;
+    url: string;
+    timeout: number;
+    size: number;
+    contentType?: string;
+    chunkMethod?: string;
+    isFastPath?: boolean;
+    chunks?: ExportFileChunk[];
+}
+interface DownloadProgress {
+    phase: "downloading" | "retrying" | "completed";
+    downloadedBytes: number;
+    totalBytes: number;
+    downloadedChunks: number;
+    totalChunks: number;
+    currentChunkIndex?: number;
+    speedBytesPerSecond: number;
+    estimatedRemainingSeconds?: number;
+    elapsedMs: number;
+    retryCount: number;
+}
+interface DownloadFileOptions extends ExportFileOptions {
+    /** Prefer File System Access API when available. Defaults to true. */
+    preferFileSystemAccess?: boolean;
+    /** Continue a matching IndexedDB checkpoint when the selected file is the same entry. */
+    resume?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    onProgress?: (progress: DownloadProgress) => void;
+    /** Use a previously selected file handle, primarily for resumeDownload. */
+    fileHandle?: FileSystemFileHandleLike;
+    /** How this download uses the client's `downloadCache`. Defaults to `default`. */
+    cache?: DownloadCacheMode;
+}
+interface DownloadResumeOptions {
+    signal?: AbortSignal;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    onProgress?: (progress: DownloadProgress) => void;
+}
+interface DownloadResult {
+    /** Absent when the file was served from the download cache without contacting Mountra. */
+    export?: ExportFileResponse;
+    downloadKey: string;
+    downloadedBytes: number;
+    /** Bytes served from the download cache instead of the network. */
+    cachedBytes: number;
+    resumed: boolean;
+    fileHandle?: FileSystemFileHandleLike;
+    blob?: Blob;
+}
+interface DownloadCheckpointChunk {
+    index: number;
+    offset: number;
+    size: number;
+    storageKey: string;
+    downloadedBytes: number;
+    completed: boolean;
+}
+interface DownloadCheckpointRequest {
+    workspaceCuid?: string;
+    workspaceId?: number | string;
+    path?: string;
+    ino?: number | string;
+    timeout?: number;
+    contentDisposition?: string;
+    downloadFilename?: string;
+}
+interface DownloadCheckpoint {
+    version: 1;
+    key: string;
+    requestKey: string;
+    request: DownloadCheckpointRequest;
+    path: string;
+    size: number;
+    chunks: DownloadCheckpointChunk[];
+    fileHandle?: FileSystemFileHandleLike;
+    updatedAt: number;
+}
+interface DownloadCheckpointStore {
+    load(key: string): Promise<DownloadCheckpoint | null>;
+    save(key: string, checkpoint: DownloadCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+    list(): Promise<DownloadCheckpoint[]>;
+}
+declare class InMemoryDownloadCheckpointStore implements DownloadCheckpointStore {
+    private readonly records;
+    load(key: string): Promise<DownloadCheckpoint | null>;
+    save(key: string, checkpoint: DownloadCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+    list(): Promise<DownloadCheckpoint[]>;
+}
+declare class IndexedDBDownloadCheckpointStore implements DownloadCheckpointStore {
+    private readonly fallback;
+    private databasePromise?;
+    load(key: string): Promise<DownloadCheckpoint | null>;
+    save(key: string, checkpoint: DownloadCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+    list(): Promise<DownloadCheckpoint[]>;
+    private openDatabase;
+    private request;
+}
+declare class DownloadHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface DownloadTransport {
+    readonly baseUrl: string;
+    readonly clientSelector: WorkspaceSelector;
+    readonly fetchImpl: typeof globalThis.fetch;
+    readonly checkpointStore: DownloadCheckpointStore;
+    readonly cache: DownloadCache | null;
+    requestJson(path: string, body: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+declare class MountraDownloader {
+    private readonly transport;
+    constructor(transport: DownloadTransport);
+    exportFile(options: ExportFileOptions): Promise<ExportFileResponse>;
+    downloadFile(options: DownloadFileOptions): Promise<DownloadResult>;
+    downloadExport(exported: ExportFileResponse, options?: DownloadFileOptions): Promise<DownloadResult>;
+    resumeDownload(downloadKey: string, options?: DownloadResumeOptions): Promise<DownloadResult>;
+    listResumableDownloads(): Promise<DownloadCheckpoint[]>;
+    clearDownloadCheckpoint(downloadKey: string): Promise<void>;
+    /** Drop the cached layout of a file that was just written, so the next download sees the new content. */
+    invalidateCachedFile(selector: WorkspaceSelector, target: {
+        path?: string;
+        ino?: number | string;
+    }): Promise<void>;
+    /**
+     * Cache a file this client just uploaded, so downloading it needs no
+     * network. Falls back to invalidation when any chunk cannot be cached.
+     */
+    cacheUploadedFile(selector: WorkspaceSelector, file: {
+        path: string;
+        ino?: number | string;
+        size: number;
+        contentType?: string;
+        chunks: Array<DownloadCacheChunk & {
+            data: Blob;
+        }>;
+    }, mode?: Exclude<DownloadCacheMode, "no-cache">): Promise<void>;
+    private cachedFileScope;
+    clearCache(selector?: WorkspaceSelector): Promise<void>;
+    cacheUsage(selector?: WorkspaceSelector): Promise<DownloadCacheUsage>;
+    private requireCacheWorkspace;
+    /** Fall back to the client workspace only when the request names none, as uploads do. */
+    private resolveRequest;
+    private exportRequest;
+    private cacheScope;
+    /** A plan that needs no network at all, when the cached layout is fresh and every chunk is cached. */
+    private loadCachedPlan;
+    private planExport;
+    private pickSaveFile;
+    private ensureWritePermission;
+    private downloadResolved;
+    private consumeResponse;
+    private consumeBytes;
+    private isSameFileHandle;
+}
+
+type MountraFileTarget = {
+    path: string;
+    ino?: never;
+} | {
+    path?: never;
+    ino: number | string;
+};
+/** A file identity accepted by `MountraClient.file()`. */
+type MountraFileLocator = WorkspaceSelector & Partial<{
+    wsid: WorkspaceId;
+}> & MountraFileTarget;
+type NormalizedMountraFileLocator = WorkspaceSelector & MountraFileTarget;
+/** Options for exporting an already identified Mountra file. */
+type MountraFileExportOptions = Omit<ExportFileOptions, "workspaceCuid" | "workspaceId" | "path" | "ino">;
+/** Options for downloading an already identified Mountra file. */
+type MountraFileDownloadOptions = Omit<DownloadFileOptions, "workspaceCuid" | "workspaceId" | "path" | "ino">;
+interface MountraFileResumeOptions extends DownloadResumeOptions {
+    /** Select a particular checkpoint; otherwise the newest matching one is used. */
+    downloadKey?: string;
+}
+/** A stable resource object for one file in one Mountra workspace. */
+declare class MountraFile {
+    private readonly client;
+    readonly locator: Readonly<NormalizedMountraFileLocator>;
+    constructor(client: MountraClient, locator: NormalizedMountraFileLocator);
+    get workspaceCuid(): string | undefined;
+    get workspaceId(): WorkspaceId | undefined;
+    /** `wsid` is the short alias used by the file-object API. */
+    get wsid(): WorkspaceId | undefined;
+    get path(): string | undefined;
+    get ino(): number | string | undefined;
+    export(options?: MountraFileExportOptions): Promise<ExportFileResponse>;
+    download(options?: MountraFileDownloadOptions): Promise<DownloadResult>;
+    resume(options?: MountraFileResumeOptions): Promise<DownloadResult>;
+}
+
 type ChunkMethod = "none" | "fix";
 type WorkspaceId = number | string;
 declare const JUMBO_CHUNK_THRESHOLD_BYTES: number;
@@ -24,10 +374,21 @@ interface MountraClientOptions extends WorkspaceSelector {
     jumboChunkCheckpointStore?: JumboChunkCheckpointStore;
     /** S3 Multipart part size. Defaults to 16 MiB. */
     jumboPartSize?: number;
+    /** IndexedDB-backed download checkpoint store. */
+    downloadCheckpointStore?: DownloadCheckpointStore;
+    /**
+     * Cache downloaded chunks locally, per workspace, in IndexedDB. Disabled
+     * unless set; pass `{}` for the defaults.
+     */
+    downloadCache?: DownloadCacheOptions;
 }
 interface UploadFileOptions extends WorkspaceSelector {
     path: string;
-    /** Number of logical chunks. Defaults to 1. */
+    /**
+     * Maximum number of fixed-size chunks. Defaults to 1. Each chunk is
+     * `ceil(size / chunkCount)` bytes except the last, so an uneven split may
+     * produce fewer chunks.
+     */
     chunkCount?: number;
     contentType?: string;
     nameConflictStrategy?: "overwrite" | "keep_both";
@@ -35,10 +396,17 @@ interface UploadFileOptions extends WorkspaceSelector {
     onProgress?: (progress: MountraProgress) => void;
     /** Persist this serializable context before the first chunk is uploaded. */
     onSessionPrepared?: (context: UploadSessionContext) => void | Promise<void>;
+    /**
+     * With the client's `downloadCache`, an uploaded file is cached by default so
+     * downloading it needs no network. `no-store` only invalidates its old entry.
+     */
+    cache?: "default" | "no-store";
 }
 interface UploadResumeOptions extends WorkspaceSelector {
     signal?: AbortSignal;
     onProgress?: (progress: MountraProgress) => void;
+    /** See `UploadFileOptions.cache`. */
+    cache?: "default" | "no-store";
 }
 interface MountraProgress {
     phase: "uploading" | "finishing";
@@ -283,7 +651,19 @@ declare class MountraClient {
     private readonly jumboChunkUploader?;
     private readonly jumboChunkCheckpointStore;
     private readonly jumboPartSize;
+    private readonly downloader;
     constructor(options: MountraClientOptions);
+    exportFile(options: ExportFileOptions): Promise<ExportFileResponse>;
+    downloadFile(options: DownloadFileOptions): Promise<DownloadResult>;
+    downloadExport(exported: ExportFileResponse, options?: DownloadFileOptions): Promise<DownloadResult>;
+    resumeDownload(downloadKey: string, options?: DownloadResumeOptions): Promise<DownloadResult>;
+    listResumableDownloads(): Promise<DownloadCheckpoint[]>;
+    clearDownloadCheckpoint(downloadKey: string): Promise<void>;
+    /** Clear the download cache of one workspace, or of every workspace when none is given. */
+    clearDownloadCache(selector?: WorkspaceSelector): Promise<void>;
+    getDownloadCacheUsage(selector?: WorkspaceSelector): Promise<DownloadCacheUsage>;
+    /** Create a stable resource object for one file in this or another workspace. */
+    file(locator: MountraFileLocator): MountraFile;
     prepareUpload(file: Blob, options: UploadFileOptions): Promise<PreparedUpload>;
     uploadFile(file: Blob, options: UploadFileOptions): Promise<UploadResult>;
     /** Generic upload entry point. It selects PUT or S3 Multipart per chunk. */
@@ -301,9 +681,11 @@ declare class MountraClient {
     private isCompatibleJumboCheckpoint;
     private assertUploadContext;
     finishUpload(uploadId: string, selector?: WorkspaceSelector): Promise<UploadResult>;
+    /** Same workspace resolution as `getWorkspaceBody`, so the cache key matches what Mountra used. */
+    private cacheWorkspace;
     private endpoint;
     private requestJson;
 }
 declare function createMountraClient(options: MountraClientOptions): MountraClient;
 
-export { type AccessToken, type ChunkMethod, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type FileChunk, type FinishUploadResponse, InMemoryJumboChunkCheckpointStore, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, MountraApiError, MountraClient, type MountraClientOptions, type MountraProgress, MountraClient as MountraSDK, type PrepareUploadResponse, type PreparedUpload, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };
+export { type AccessToken, type ChunkMethod, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type DownloadCacheChunk, type DownloadCacheFile, type DownloadCacheMode, type DownloadCacheOptions, type DownloadCacheStore, type DownloadCacheUsage, type DownloadCheckpoint, type DownloadCheckpointChunk, type DownloadCheckpointRequest, type DownloadCheckpointStore, type DownloadFileOptions, DownloadHttpError, type DownloadProgress, type DownloadResult, type DownloadResumeOptions, type ExportFileChunk, type ExportFileOptions, type ExportFileResponse, type FileChunk, type FileSystemFileHandleLike, type FileSystemWritableFileStreamLike, type FinishUploadResponse, InMemoryDownloadCacheStore, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, IndexedDBDownloadCacheStore, type IndexedDBDownloadCacheStoreOptions, IndexedDBDownloadCheckpointStore, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, MountraApiError, MountraClient, type MountraClientOptions, MountraDownloader, MountraFile, type MountraFileDownloadOptions, type MountraFileExportOptions, type MountraFileLocator, type MountraFileResumeOptions, type MountraProgress, MountraClient as MountraSDK, type NormalizedMountraFileLocator, type PrepareUploadResponse, type PreparedUpload, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };