@mountra/mountra-sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,119 @@
+/**
+ * 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>;
@@ -67,6 +183,8 @@ interface DownloadFileOptions extends ExportFileOptions {
     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;
@@ -75,9 +193,12 @@ interface DownloadResumeOptions {
     onProgress?: (progress: DownloadProgress) => void;
 }
 interface DownloadResult {
-    export: ExportFileResponse;
+    /** 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;
@@ -142,6 +263,7 @@ interface DownloadTransport {
     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 {
@@ -153,6 +275,35 @@ declare class MountraDownloader {
     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;
@@ -225,10 +376,19 @@ interface MountraClientOptions extends WorkspaceSelector {
     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";
@@ -236,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";
@@ -492,6 +659,9 @@ declare class MountraClient {
     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>;
@@ -511,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 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, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, 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 };
+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 };

package/dist/index.d.ts

@@ -1,3 +1,119 @@
+/**
+ * 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>;
@@ -67,6 +183,8 @@ interface DownloadFileOptions extends ExportFileOptions {
     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;
@@ -75,9 +193,12 @@ interface DownloadResumeOptions {
     onProgress?: (progress: DownloadProgress) => void;
 }
 interface DownloadResult {
-    export: ExportFileResponse;
+    /** 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;
@@ -142,6 +263,7 @@ interface DownloadTransport {
     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 {
@@ -153,6 +275,35 @@ declare class MountraDownloader {
     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;
@@ -225,10 +376,19 @@ interface MountraClientOptions extends WorkspaceSelector {
     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";
@@ -236,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";
@@ -492,6 +659,9 @@ declare class MountraClient {
     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>;
@@ -511,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 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, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, 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 };
+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 };