@mountra/mountra-sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,3 +1,913 @@
+// src/download.ts
+function copyCheckpoint(checkpoint) {
+  return {
+    ...checkpoint,
+    request: { ...checkpoint.request },
+    chunks: checkpoint.chunks.map((chunk) => ({ ...chunk }))
+  };
+}
+var InMemoryDownloadCheckpointStore = class {
+  records = /* @__PURE__ */ new Map();
+  async load(key) {
+    const value = this.records.get(key);
+    return value ? copyCheckpoint(value) : null;
+  }
+  async save(key, checkpoint) {
+    this.records.set(key, copyCheckpoint(checkpoint));
+  }
+  async remove(key) {
+    this.records.delete(key);
+  }
+  async list() {
+    return [...this.records.values()].map(copyCheckpoint);
+  }
+};
+var DOWNLOAD_DATABASE_NAME = "mountra-sdk";
+var DOWNLOAD_DATABASE_VERSION = 1;
+var DOWNLOAD_STORE_NAME = "download-checkpoints";
+function getIndexedDb() {
+  return globalThis.indexedDB ?? null;
+}
+var IndexedDBDownloadCheckpointStore = class {
+  fallback = new InMemoryDownloadCheckpointStore();
+  databasePromise;
+  async load(key) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.load(key);
+    }
+    try {
+      const value = await this.request(
+        database,
+        "readonly",
+        (store) => store.get(key)
+      );
+      return value ? copyCheckpoint(value) : null;
+    } catch {
+      return this.fallback.load(key);
+    }
+  }
+  async save(key, checkpoint) {
+    const value = copyCheckpoint(checkpoint);
+    const database = await this.openDatabase();
+    if (!database) {
+      await this.fallback.save(key, value);
+      return;
+    }
+    try {
+      await this.request(database, "readwrite", (store) => store.put(value, key));
+    } catch {
+      await this.fallback.save(key, value);
+    }
+  }
+  async remove(key) {
+    const database = await this.openDatabase();
+    if (!database) {
+      await this.fallback.remove(key);
+      return;
+    }
+    try {
+      await this.request(database, "readwrite", (store) => store.delete(key));
+    } catch {
+      await this.fallback.remove(key);
+    }
+  }
+  async list() {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.list();
+    }
+    try {
+      const values = await this.request(
+        database,
+        "readonly",
+        (store) => store.getAll()
+      );
+      return values.map(copyCheckpoint);
+    } catch {
+      return this.fallback.list();
+    }
+  }
+  async openDatabase() {
+    if (!this.databasePromise) {
+      const indexedDb = getIndexedDb();
+      if (!indexedDb) {
+        this.databasePromise = Promise.resolve(null);
+      } else {
+        this.databasePromise = new Promise((resolve) => {
+          let request;
+          try {
+            request = indexedDb.open(DOWNLOAD_DATABASE_NAME, DOWNLOAD_DATABASE_VERSION);
+          } catch {
+            resolve(null);
+            return;
+          }
+          request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(DOWNLOAD_STORE_NAME)) {
+              request.result.createObjectStore(DOWNLOAD_STORE_NAME);
+            }
+          };
+          request.onsuccess = () => resolve(request.result);
+          request.onerror = () => resolve(null);
+          request.onblocked = () => resolve(null);
+        });
+      }
+    }
+    return this.databasePromise;
+  }
+  request(database, mode, createRequest) {
+    return new Promise((resolve, reject) => {
+      let transaction;
+      let request;
+      try {
+        transaction = database.transaction(DOWNLOAD_STORE_NAME, mode);
+        request = createRequest(transaction.objectStore(DOWNLOAD_STORE_NAME));
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      let result;
+      request.onsuccess = () => {
+        result = request.result;
+      };
+      request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
+      transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
+    });
+  }
+};
+var DownloadHttpError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "DownloadHttpError";
+    this.status = status;
+  }
+};
+function getShowSaveFilePicker() {
+  return globalThis.showSaveFilePicker ?? null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readSafeNumber(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`Mountra export response field ${field} is invalid`);
+  }
+  return value;
+}
+function readString(value, field) {
+  if (typeof value !== "string" || !value) {
+    throw new TypeError(`Mountra export response field ${field} is invalid`);
+  }
+  return value;
+}
+function ensureExportFileResponse(value) {
+  if (!isRecord(value)) {
+    throw new TypeError("Mountra export response is invalid");
+  }
+  const response = {
+    path: readString(value.path, "path"),
+    storageKey: readString(value.storage_key, "storage_key"),
+    url: readString(value.url, "url"),
+    timeout: readSafeNumber(value.timeout, "timeout"),
+    size: readSafeNumber(value.size, "size")
+  };
+  try {
+    new URL(response.url);
+  } catch {
+    throw new TypeError("Mountra export response field url is invalid");
+  }
+  if (typeof value.content_type === "string" && value.content_type) {
+    response.contentType = value.content_type;
+  }
+  if (typeof value.chunk_method === "string") {
+    response.chunkMethod = value.chunk_method;
+  }
+  if (typeof value.is_fast_path === "boolean") {
+    response.isFastPath = value.is_fast_path;
+  }
+  if (Array.isArray(value.chunks)) {
+    response.chunks = value.chunks.map((rawChunk, position) => {
+      if (!isRecord(rawChunk)) {
+        throw new TypeError(`Mountra export response chunk ${position} is invalid`);
+      }
+      const chunk = {
+        index: readSafeNumber(rawChunk.index, `chunks[${position}].index`),
+        offset: readSafeNumber(rawChunk.offset, `chunks[${position}].offset`),
+        size: readSafeNumber(rawChunk.size, `chunks[${position}].size`),
+        storageKey: readString(rawChunk.storage_key, `chunks[${position}].storage_key`),
+        url: readString(rawChunk.url, `chunks[${position}].url`)
+      };
+      try {
+        new URL(chunk.url);
+      } catch {
+        throw new TypeError(`Mountra export response chunk ${position} URL is invalid`);
+      }
+      return chunk;
+    });
+    response.chunks.sort((left, right) => left.index - right.index);
+    response.chunks.forEach((chunk, index) => {
+      if (chunk.index !== index || chunk.offset + chunk.size > response.size || index > 0 && response.chunks[index - 1].offset + response.chunks[index - 1].size !== chunk.offset) {
+        throw new TypeError("Mountra export response has an invalid chunk layout");
+      }
+    });
+    const finalChunk = response.chunks[response.chunks.length - 1];
+    if (finalChunk && finalChunk.offset + finalChunk.size !== response.size) {
+      throw new TypeError("Mountra export response chunks do not cover the complete file");
+    }
+  }
+  return response;
+}
+function validateRetryOption(value, name) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new DOMException("The download was aborted", "AbortError");
+  }
+}
+function isAbortError(error, signal) {
+  return signal?.aborted === true || error instanceof DOMException && error.name === "AbortError";
+}
+function isRetryableError(error) {
+  if (error instanceof DownloadHttpError) {
+    return [408, 425, 429, 500, 502, 503, 504].includes(error.status);
+  }
+  return true;
+}
+function waitForRetry(delayMs, signal) {
+  if (delayMs <= 0) {
+    throwIfAborted(signal);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let timer;
+    const onAbort = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("The download was aborted", "AbortError"));
+    };
+    timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+var SpeedWindow = class {
+  samples = [];
+  record(bytes, at) {
+    this.samples.push({ at, bytes });
+    const cutoff = at - 1e3;
+    while (this.samples.length > 1 && this.samples[0].at < cutoff) {
+      this.samples.shift();
+    }
+    const first = this.samples[0];
+    if (!first || first.bytes === bytes) {
+      return 0;
+    }
+    const seconds = Math.max((at - first.at) / 1e3, 1e-3);
+    return (bytes - first.bytes) / seconds;
+  }
+};
+var BlobDownloadSink = class {
+  parts = [];
+  async write(bytes) {
+    this.parts.push(bytes.slice());
+  }
+  async flush() {
+  }
+  async finalize() {
+  }
+  blob(contentType) {
+    const buffers = this.parts.map((part) => {
+      const buffer = new ArrayBuffer(part.byteLength);
+      new Uint8Array(buffer).set(part);
+      return buffer;
+    });
+    return new Blob(buffers, contentType ? { type: contentType } : void 0);
+  }
+};
+var FileSystemDownloadSink = class {
+  constructor(handle) {
+    this.handle = handle;
+  }
+  handle;
+  writable = null;
+  position = 0;
+  openedOnce = false;
+  async write(bytes, position) {
+    if (!this.writable) {
+      const keepExistingData = this.openedOnce || position > 0;
+      this.writable = await this.handle.createWritable({ keepExistingData });
+      if (position > 0) {
+        await this.writable.seek(position);
+      }
+      this.position = position;
+      this.openedOnce = true;
+    }
+    if (this.position !== position) {
+      throw new Error("File System Access writer position does not match the download checkpoint");
+    }
+    await this.writable.write(bytes);
+    this.position += bytes.byteLength;
+  }
+  async flush() {
+    if (this.writable) {
+      const writable = this.writable;
+      await writable.close();
+      this.writable = null;
+    }
+  }
+  async finalize(size) {
+    if (!this.writable) {
+      this.writable = await this.handle.createWritable({ keepExistingData: this.openedOnce });
+      this.openedOnce = true;
+      await this.writable.seek(size);
+    }
+    await this.writable.truncate(size);
+    const writable = this.writable;
+    this.writable = null;
+    await writable.close();
+  }
+  async abort() {
+    if (!this.writable) {
+      return;
+    }
+    const writable = this.writable;
+    this.writable = null;
+    if (writable.abort) {
+      await writable.abort();
+    } else {
+      await writable.close();
+    }
+  }
+};
+function downloadRequestFromOptions(options) {
+  if (options.path === void 0 && options.ino === void 0) {
+    throw new TypeError("download target requires path or ino");
+  }
+  if (options.path !== void 0 && !options.path.trim()) {
+    throw new TypeError("download path cannot be empty");
+  }
+  return {
+    ...options.workspaceCuid !== void 0 ? { workspaceCuid: options.workspaceCuid } : {},
+    ...options.workspaceId !== void 0 ? { workspaceId: options.workspaceId } : {},
+    ...options.path !== void 0 ? { path: options.path } : {},
+    ...options.ino !== void 0 ? { ino: options.ino } : {},
+    ...options.timeout !== void 0 ? { timeout: options.timeout } : {},
+    ...options.contentDisposition !== void 0 ? { contentDisposition: options.contentDisposition } : {},
+    ...options.downloadFilename !== void 0 ? { downloadFilename: options.downloadFilename } : {}
+  };
+}
+function requestBodyFromCheckpoint(request) {
+  return {
+    ...request.workspaceCuid !== void 0 ? { workspace_cuid: request.workspaceCuid } : {},
+    ...request.workspaceId !== void 0 ? { workspace_id: request.workspaceId } : {},
+    ...request.path !== void 0 ? { path: request.path } : {},
+    ...request.ino !== void 0 ? { ino: request.ino } : {},
+    ...request.timeout !== void 0 ? { timeout: request.timeout } : {},
+    ...request.contentDisposition !== void 0 ? { content_disposition: request.contentDisposition } : {},
+    ...request.downloadFilename !== void 0 ? { download_filename: request.downloadFilename } : {}
+  };
+}
+function requestKey(request, baseUrl) {
+  return encodeURIComponent(
+    JSON.stringify({
+      baseUrl,
+      workspaceCuid: request.workspaceCuid ?? null,
+      workspaceId: request.workspaceId ?? null,
+      path: request.path ?? null,
+      ino: request.ino ?? null
+    })
+  );
+}
+function buildDownloadChunks(exported, useClientAssembly) {
+  if (useClientAssembly && exported.chunks && exported.chunks.length > 1) {
+    return exported.chunks;
+  }
+  return [
+    {
+      index: 0,
+      offset: 0,
+      size: exported.size,
+      storageKey: exported.storageKey,
+      url: exported.url
+    }
+  ];
+}
+function buildDownloadKey(exported, chunks, baseUrl, request) {
+  return encodeURIComponent(
+    JSON.stringify({
+      request: requestKey(request, baseUrl),
+      path: exported.path,
+      size: exported.size,
+      chunks: chunks.map((chunk) => [chunk.index, chunk.offset, chunk.size, chunk.storageKey])
+    })
+  );
+}
+function checkpointMatches(checkpoint, exported, chunks) {
+  if (checkpoint.version !== 1 || checkpoint.path !== exported.path || checkpoint.size !== exported.size) {
+    return false;
+  }
+  if (checkpoint.chunks.length !== chunks.length) {
+    return false;
+  }
+  return checkpoint.chunks.every((saved, index) => {
+    const current = chunks[index];
+    return Boolean(
+      current && saved.index === current.index && saved.offset === current.offset && saved.size === current.size && saved.storageKey === current.storageKey && saved.downloadedBytes >= 0 && saved.downloadedBytes <= saved.size
+    );
+  });
+}
+function createCheckpoint(key, baseUrl, request, exported, chunks, fileHandle) {
+  return {
+    version: 1,
+    key,
+    requestKey: requestKey(request, baseUrl),
+    request: { ...request },
+    path: exported.path,
+    size: exported.size,
+    chunks: chunks.map((chunk) => ({
+      index: chunk.index,
+      offset: chunk.offset,
+      size: chunk.size,
+      storageKey: chunk.storageKey,
+      downloadedBytes: 0,
+      completed: chunk.size === 0
+    })),
+    ...fileHandle ? { fileHandle } : {},
+    updatedAt: Date.now()
+  };
+}
+function totalDownloadedBytes(checkpoint) {
+  return checkpoint.chunks.reduce((total, chunk) => total + chunk.downloadedBytes, 0);
+}
+function completedChunkCount(checkpoint) {
+  return checkpoint.chunks.filter((chunk) => chunk.completed).length;
+}
+function defaultFilename(exported, requested) {
+  const candidate = requested?.trim() || exported.path.split("/").filter(Boolean).pop() || "download";
+  return candidate.replace(/[\\/\r\n]/g, "_") || "download";
+}
+function triggerBrowserDownload(blob, filename) {
+  const documentValue = globalThis.document;
+  const urlApi = globalThis.URL;
+  if (!documentValue || !urlApi?.createObjectURL) {
+    return;
+  }
+  const url = urlApi.createObjectURL(blob);
+  const anchor = documentValue.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.style.display = "none";
+  documentValue.body?.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => urlApi.revokeObjectURL(url), 0);
+}
+var MountraDownloader = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async exportFile(options) {
+    const request = downloadRequestFromOptions(options);
+    return ensureExportFileResponse(
+      await this.transport.requestJson(
+        "/file/export",
+        requestBodyFromCheckpoint(request),
+        options.signal
+      )
+    );
+  }
+  async downloadFile(options) {
+    const preferFileSystemAccess = options.preferFileSystemAccess !== false;
+    const fileHandle = options.fileHandle ?? (preferFileSystemAccess && getShowSaveFilePicker() ? await this.pickSaveFile(options.downloadFilename ?? options.path?.split("/").filter(Boolean).pop()) : void 0);
+    const exported = await this.exportFile(options);
+    return this.downloadExport(exported, { ...options, ...fileHandle ? { fileHandle } : {} });
+  }
+  async downloadExport(exported, options = { path: exported.path }) {
+    let fileHandle = options.fileHandle;
+    if (!fileHandle && options.preferFileSystemAccess !== false && getShowSaveFilePicker()) {
+      fileHandle = await this.pickSaveFile(
+        options.downloadFilename ?? defaultFilename(exported),
+        exported.contentType
+      );
+    }
+    const request = downloadRequestFromOptions(
+      options.path === void 0 && options.ino === void 0 ? { ...options, path: exported.path } : options
+    );
+    return this.downloadResolved(exported, request, options, fileHandle, false);
+  }
+  async resumeDownload(downloadKey, options = {}) {
+    if (!downloadKey.trim()) {
+      throw new TypeError("downloadKey is required");
+    }
+    const checkpoint = await this.transport.checkpointStore.load(downloadKey);
+    if (!checkpoint || !checkpoint.fileHandle) {
+      throw new Error("No resumable File System Access download was found");
+    }
+    await this.ensureWritePermission(checkpoint.fileHandle);
+    const exported = await this.exportFile({
+      ...checkpoint.request,
+      signal: options.signal
+    });
+    return this.downloadResolved(
+      exported,
+      checkpoint.request,
+      options,
+      checkpoint.fileHandle,
+      true
+    );
+  }
+  listResumableDownloads() {
+    return this.transport.checkpointStore.list();
+  }
+  clearDownloadCheckpoint(downloadKey) {
+    return this.transport.checkpointStore.remove(downloadKey);
+  }
+  async pickSaveFile(requestedFilename, contentType) {
+    const picker = getShowSaveFilePicker();
+    if (!picker) {
+      throw new Error("File System Access API is not available");
+    }
+    const types = contentType ? [{ description: contentType, accept: { [contentType]: ["." + (requestedFilename?.split(".").pop() || "bin")] } }] : void 0;
+    return picker({
+      suggestedName: requestedFilename?.trim() || "download",
+      ...types ? { types } : {}
+    });
+  }
+  async ensureWritePermission(handle) {
+    if (!handle.queryPermission && !handle.requestPermission) {
+      return;
+    }
+    const descriptor = { mode: "readwrite" };
+    const current = await handle.queryPermission?.(descriptor);
+    if (current === "granted") {
+      return;
+    }
+    const requested = await handle.requestPermission?.(descriptor);
+    if (requested !== void 0 && requested !== "granted") {
+      throw new DOMException("Write permission was not granted", "NotAllowedError");
+    }
+  }
+  async downloadResolved(exported, request, options, fileHandle, forceResume) {
+    const useClientAssembly = Boolean(fileHandle && (exported.chunks?.length ?? 0) > 1);
+    const chunks = buildDownloadChunks(exported, useClientAssembly);
+    const key = buildDownloadKey(exported, chunks, this.transport.baseUrl, request);
+    const existing = await this.transport.checkpointStore.load(key);
+    const resumeRequested = !("resume" in options) || options.resume !== false;
+    let checkpoint = existing && checkpointMatches(existing, exported, chunks) && (forceResume || resumeRequested) && (forceResume || fileHandle && await this.isSameFileHandle(existing.fileHandle, fileHandle)) ? existing : createCheckpoint(key, this.transport.baseUrl, request, exported, chunks, fileHandle);
+    if (fileHandle) {
+      checkpoint.fileHandle = fileHandle;
+    }
+    const resumed = totalDownloadedBytes(checkpoint) > 0;
+    const maxRetries = validateRetryOption(options.maxRetries, "maxRetries") ?? 3;
+    const retryDelayMs = validateRetryOption(options.retryDelayMs, "retryDelayMs") ?? 500;
+    const sink = fileHandle ? new FileSystemDownloadSink(fileHandle) : new BlobDownloadSink();
+    const speedWindow = new SpeedWindow();
+    const startedAt = Date.now();
+    let retryCount = 0;
+    let lastCheckpointAt = 0;
+    const emit = (phase, currentChunkIndex) => {
+      const downloadedBytes = totalDownloadedBytes(checkpoint);
+      const speedBytesPerSecond = speedWindow.record(downloadedBytes, Date.now());
+      const remainingBytes = Math.max(exported.size - downloadedBytes, 0);
+      options.onProgress?.({
+        phase,
+        downloadedBytes,
+        totalBytes: exported.size,
+        downloadedChunks: completedChunkCount(checkpoint),
+        totalChunks: checkpoint.chunks.length,
+        ...currentChunkIndex !== void 0 ? { currentChunkIndex } : {},
+        speedBytesPerSecond,
+        ...speedBytesPerSecond > 0 && remainingBytes > 0 ? { estimatedRemainingSeconds: remainingBytes / speedBytesPerSecond } : {},
+        elapsedMs: Date.now() - startedAt,
+        retryCount
+      });
+    };
+    const persist = async (force) => {
+      const now = Date.now();
+      if (!force && now - lastCheckpointAt < 1e3) {
+        return;
+      }
+      await sink.flush();
+      checkpoint.updatedAt = now;
+      await this.transport.checkpointStore.save(key, checkpoint);
+      lastCheckpointAt = now;
+    };
+    await this.transport.checkpointStore.save(key, checkpoint);
+    try {
+      for (const chunk of chunks) {
+        const savedChunk = checkpoint.chunks[chunk.index];
+        if (!savedChunk) {
+          throw new Error(`Missing download checkpoint for chunk ${chunk.index}`);
+        }
+        if (savedChunk.completed) {
+          continue;
+        }
+        let attempt = 0;
+        while (true) {
+          throwIfAborted(options.signal);
+          const rangeStart = savedChunk.downloadedBytes;
+          try {
+            const response = await this.transport.fetchImpl(chunk.url, {
+              method: "GET",
+              ...rangeStart > 0 ? { headers: { Range: `bytes=${rangeStart}-` } } : {},
+              ...options.signal ? { signal: options.signal } : {}
+            });
+            if (!response.ok) {
+              throw new DownloadHttpError(
+                response.status,
+                `Download for chunk ${chunk.index} failed with HTTP ${response.status}`
+              );
+            }
+            await this.consumeResponse(
+              response,
+              chunk,
+              savedChunk,
+              sink,
+              exported.size,
+              emit,
+              persist,
+              options.signal
+            );
+            if (savedChunk.downloadedBytes !== savedChunk.size) {
+              throw new Error(
+                `Download for chunk ${chunk.index} ended at ${savedChunk.downloadedBytes} of ${savedChunk.size} bytes`
+              );
+            }
+            savedChunk.completed = true;
+            await persist(true);
+            emit("downloading", chunk.index);
+            break;
+          } catch (error) {
+            await persist(true);
+            if (isAbortError(error, options.signal) || !isRetryableError(error) || attempt >= maxRetries) {
+              throw error;
+            }
+            attempt += 1;
+            retryCount += 1;
+            emit("retrying", chunk.index);
+            await waitForRetry(Math.min(retryDelayMs * 2 ** (attempt - 1), 3e4), options.signal);
+          }
+        }
+      }
+      if (totalDownloadedBytes(checkpoint) !== exported.size) {
+        throw new Error("Download completed with an unexpected byte count");
+      }
+      if (fileHandle) {
+        await sink.finalize(exported.size);
+      } else {
+        await sink.finalize();
+      }
+      await this.transport.checkpointStore.remove(key);
+      emit("completed");
+      const blob = sink instanceof BlobDownloadSink ? sink.blob(exported.contentType) : void 0;
+      if (blob) {
+        const filename = "downloadFilename" in options ? options.downloadFilename : void 0;
+        triggerBrowserDownload(blob, defaultFilename(exported, filename));
+      }
+      return {
+        export: exported,
+        downloadKey: key,
+        downloadedBytes: exported.size,
+        resumed,
+        ...fileHandle ? { fileHandle } : {},
+        ...blob ? { blob } : {}
+      };
+    } catch (error) {
+      await persist(true);
+      throw error;
+    }
+  }
+  async consumeResponse(response, chunk, savedChunk, sink, totalSize, emit, persist, signal) {
+    const sourceOffset = savedChunk.downloadedBytes;
+    let bytesToSkip = response.status === 200 && sourceOffset > 0 ? sourceOffset : 0;
+    const reader = response.body?.getReader();
+    if (!reader) {
+      const body = new Uint8Array(await response.arrayBuffer());
+      await this.consumeBytes(body, bytesToSkip, chunk, savedChunk, sink, totalSize, emit, persist, signal);
+      return;
+    }
+    try {
+      while (true) {
+        throwIfAborted(signal);
+        const next = await reader.read();
+        if (next.done) {
+          break;
+        }
+        const bytes = next.value;
+        if (bytesToSkip > 0) {
+          const skipped = Math.min(bytesToSkip, bytes.byteLength);
+          bytesToSkip -= skipped;
+          if (skipped === bytes.byteLength) {
+            continue;
+          }
+          await this.consumeBytes(
+            bytes.subarray(skipped),
+            0,
+            chunk,
+            savedChunk,
+            sink,
+            totalSize,
+            emit,
+            persist,
+            signal
+          );
+        } else {
+          await this.consumeBytes(bytes, 0, chunk, savedChunk, sink, totalSize, emit, persist, signal);
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (bytesToSkip > 0) {
+      throw new Error(`Download response did not contain the saved offset for chunk ${chunk.index}`);
+    }
+  }
+  async consumeBytes(bytes, offset, chunk, savedChunk, sink, totalSize, emit, persist, signal) {
+    const remaining = chunk.size - savedChunk.downloadedBytes;
+    const writableBytes = bytes.byteLength - offset;
+    if (writableBytes > remaining) {
+      throw new Error(`Download response for chunk ${chunk.index} is larger than expected`);
+    }
+    if (writableBytes === 0) {
+      return;
+    }
+    throwIfAborted(signal);
+    const payload = bytes.subarray(offset);
+    const position = chunk.offset + savedChunk.downloadedBytes;
+    if (sink instanceof FileSystemDownloadSink) {
+      await sink.write(payload, position);
+    } else {
+      await sink.write(payload);
+    }
+    savedChunk.downloadedBytes += payload.byteLength;
+    emit("downloading", chunk.index);
+    await persist(false);
+    if (savedChunk.downloadedBytes > totalSize) {
+      throw new Error("Download byte count exceeded the exported file size");
+    }
+  }
+  async isSameFileHandle(savedHandle, selectedHandle) {
+    if (!savedHandle) {
+      return false;
+    }
+    if (savedHandle === selectedHandle) {
+      return true;
+    }
+    if (savedHandle.isSameEntry) {
+      try {
+        return await savedHandle.isSameEntry(selectedHandle);
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+};
+
+// src/file.ts
+function normalizeMountraFileLocator(locator, fallbackWorkspace = {}) {
+  if (!locator || typeof locator !== "object") {
+    throw new TypeError("Mountra file locator is required");
+  }
+  const hasPath = locator.path !== void 0;
+  const hasIno = locator.ino !== void 0;
+  if (hasPath === hasIno) {
+    throw new TypeError("Mountra file locator requires exactly one of path or ino");
+  }
+  const workspaceId = locator.workspaceId ?? locator.wsid ?? fallbackWorkspace.workspaceId;
+  if (locator.workspaceId !== void 0 && locator.wsid !== void 0 && String(locator.workspaceId) !== String(locator.wsid)) {
+    throw new TypeError("workspaceId and wsid must identify the same workspace");
+  }
+  const workspaceCuid = locator.workspaceCuid ?? fallbackWorkspace.workspaceCuid;
+  if (workspaceCuid === void 0 && workspaceId === void 0) {
+    throw new TypeError("workspaceCuid, workspaceId, or wsid is required");
+  }
+  if (hasPath) {
+    const path = normalizePath(locator.path);
+    return {
+      ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+      ...workspaceId !== void 0 ? { workspaceId } : {},
+      path
+    };
+  }
+  return {
+    ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+    ...workspaceId !== void 0 ? { workspaceId } : {},
+    ino: normalizeIno(locator.ino)
+  };
+}
+var MountraFile = class {
+  constructor(client, locator) {
+    this.client = client;
+    this.locator = Object.freeze({ ...locator });
+  }
+  client;
+  locator;
+  get workspaceCuid() {
+    return this.locator.workspaceCuid;
+  }
+  get workspaceId() {
+    return this.locator.workspaceId;
+  }
+  /** `wsid` is the short alias used by the file-object API. */
+  get wsid() {
+    return this.locator.workspaceId;
+  }
+  get path() {
+    return "path" in this.locator ? this.locator.path : void 0;
+  }
+  get ino() {
+    return "ino" in this.locator ? this.locator.ino : void 0;
+  }
+  export(options = {}) {
+    return this.client.exportFile({ ...options, ...this.locator });
+  }
+  download(options = {}) {
+    return this.client.downloadFile({ ...options, ...this.locator });
+  }
+  async resume(options = {}) {
+    const { downloadKey, ...resumeOptions } = options;
+    const checkpoints = await this.client.listResumableDownloads();
+    const candidates = checkpoints.filter(
+      (checkpoint2) => checkpoint2.fileHandle && matchesLocator(checkpoint2.request, this.locator)
+    );
+    const checkpoint = downloadKey ? candidates.find((candidate) => candidate.key === downloadKey) : [...candidates].sort((left, right) => right.updatedAt - left.updatedAt)[0];
+    if (!checkpoint) {
+      if (downloadKey) {
+        throw new Error("Download checkpoint does not belong to this Mountra file");
+      }
+      throw new Error("No resumable download was found for this Mountra file");
+    }
+    return this.client.resumeDownload(checkpoint.key, resumeOptions);
+  }
+};
+function matchesLocator(request, locator) {
+  if (locator.workspaceCuid !== void 0 && request.workspaceCuid !== locator.workspaceCuid) {
+    return false;
+  }
+  if (locator.workspaceId !== void 0 && String(request.workspaceId) !== String(locator.workspaceId)) {
+    return false;
+  }
+  if ("path" in locator) {
+    if (request.path === void 0 || request.ino !== void 0) {
+      return false;
+    }
+    try {
+      return normalizePath(request.path) === locator.path;
+    } catch {
+      return false;
+    }
+  }
+  return String(request.ino) === String(locator.ino) && request.path === void 0;
+}
+function normalizePath(value) {
+  if (!value || !value.trim()) {
+    throw new TypeError("Mountra file path cannot be empty");
+  }
+  const raw = value.trim();
+  const absolute = raw.startsWith("/") ? raw : `/${raw}`;
+  const segments = absolute.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+  const stack = [];
+  for (const segment of segments) {
+    if (segment === "..") {
+      stack.pop();
+      continue;
+    }
+    stack.push(segment);
+  }
+  return stack.length === 0 ? "/" : `/${stack.join("/")}`;
+}
+function normalizeIno(value) {
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new TypeError("Mountra file ino must be a non-negative safe integer");
+    }
+    return value;
+  }
+  if (!/^\d+$/.test(value)) {
+    throw new TypeError("Mountra file ino must be a non-negative integer string");
+  }
+  return value;
+}
+
 // src/upload.ts
 var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
 var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
@@ -17,7 +927,7 @@ var MountraApiError = class extends Error {
 };
 var memoryCheckpointRecords = /* @__PURE__ */ new Map();
 function parseJumboCheckpoint(value) {
-  if (!isRecord(value) || value.version !== 1 || typeof value.storageKey !== "string") {
+  if (!isRecord2(value) || value.version !== 1 || typeof value.storageKey !== "string") {
     return null;
   }
   if (typeof value.chunkIndex !== "number" || typeof value.chunkSize !== "number" || typeof value.chunkSha256 !== "string" || typeof value.partSize !== "number" || typeof value.uploadId !== "string" || !Array.isArray(value.parts)) {
@@ -25,7 +935,7 @@ function parseJumboCheckpoint(value) {
   }
   const parts = [];
   for (const part of value.parts) {
-    if (!isRecord(part)) {
+    if (!isRecord2(part)) {
       return null;
     }
     if (typeof part.partNumber !== "number" || typeof part.etag !== "string" || typeof part.size !== "number" || typeof part.sha256 !== "string") {
@@ -198,17 +1108,17 @@ function getWorkspaceBody(clientSelector, requestSelector) {
     ...workspaceId !== void 0 ? { workspace_id: workspaceId } : {}
   };
 }
-function throwIfAborted(signal) {
+function throwIfAborted2(signal) {
   if (!signal?.aborted) {
     return;
   }
   throw new DOMException("The upload was aborted", "AbortError");
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
 function parseApiErrorBody(body) {
-  if (!isRecord(body)) {
+  if (!isRecord2(body)) {
     return {};
   }
   return {
@@ -217,7 +1127,7 @@ function parseApiErrorBody(body) {
   };
 }
 function ensurePrepareResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra prepare response is invalid");
   }
   if (!Array.isArray(value.upload_targets)) {
@@ -226,13 +1136,13 @@ function ensurePrepareResponse(value) {
   return value;
 }
 function ensureFinishResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra finish response is invalid");
   }
   return value;
 }
 function ensureUploadStatusResponse(value) {
-  if (!isRecord(value) || typeof value.upload_id !== "string") {
+  if (!isRecord2(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra upload status response is invalid");
   }
   if (!Array.isArray(value.chunks)) {
@@ -283,6 +1193,7 @@ var MountraClient = class {
   jumboChunkUploader;
   jumboChunkCheckpointStore;
   jumboPartSize;
+  downloader;
   constructor(options) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiPrefix = normalizeApiPrefix(options.apiPrefix ?? "/api");
@@ -301,6 +1212,38 @@ var MountraClient = class {
       throw new Error("fetch is not available; provide fetch in MountraClientOptions");
     }
     this.fetchImpl = fetchImpl;
+    this.downloader = new MountraDownloader({
+      baseUrl: this.baseUrl,
+      clientSelector: this.clientSelector,
+      fetchImpl: this.fetchImpl,
+      checkpointStore: options.downloadCheckpointStore ?? new IndexedDBDownloadCheckpointStore(),
+      requestJson: (path, body, signal) => this.requestJson(path, body, signal)
+    });
+  }
+  async exportFile(options) {
+    return this.downloader.exportFile(options);
+  }
+  async downloadFile(options) {
+    return this.downloader.downloadFile(options);
+  }
+  async downloadExport(exported, options) {
+    return this.downloader.downloadExport(exported, options);
+  }
+  async resumeDownload(downloadKey, options) {
+    return this.downloader.resumeDownload(downloadKey, options);
+  }
+  listResumableDownloads() {
+    return this.downloader.listResumableDownloads();
+  }
+  clearDownloadCheckpoint(downloadKey) {
+    return this.downloader.clearDownloadCheckpoint(downloadKey);
+  }
+  /** Create a stable resource object for one file in this or another workspace. */
+  file(locator) {
+    return new MountraFile(
+      this,
+      normalizeMountraFileLocator(locator, this.clientSelector)
+    );
   }
   async prepareUpload(file, options) {
     const chunks = splitFileIntoChunks(file, options.chunkCount ?? 1);
@@ -308,7 +1251,7 @@ var MountraClient = class {
     const contentHash = await sha256Hex(file);
     const chunkMethod = chunks.length === 1 ? "none" : "fix";
     const contentType = options.contentType ?? ("type" in file ? file.type : void 0);
-    throwIfAborted(options.signal);
+    throwIfAborted2(options.signal);
     const response = ensurePrepareResponse(
       await this.requestJson("/upload/prepare", {
         ...getWorkspaceBody(this.clientSelector, options),
@@ -411,7 +1354,7 @@ var MountraClient = class {
       if (!chunk || target.chunk_index !== position) {
         throw new Error("Mountra upload targets must contain contiguous chunk indexes");
       }
-      throwIfAborted(options.signal);
+      throwIfAborted2(options.signal);
       if (isJumboChunk(chunk.size)) {
         const checkpointKey = this.buildJumboCheckpointKey(context, target, options);
         jumboCheckpointKeys.add(checkpointKey);
@@ -454,7 +1397,7 @@ var MountraClient = class {
         totalChunks: orderedTargets.length
       });
     }
-    throwIfAborted(options.signal);
+    throwIfAborted2(options.signal);
     options.onProgress?.({
       phase: "finishing",
       uploadedBytes: file.size,
@@ -558,7 +1501,7 @@ var MountraClient = class {
     let uploadedBytes = 0;
     let uploadedParts = 0;
     for (let partNumber = 1; partNumber <= totalParts; partNumber += 1) {
-      throwIfAborted(options.signal);
+      throwIfAborted2(options.signal);
       const start = (partNumber - 1) * this.jumboPartSize;
       const partBlob = chunk.blob.slice(start, Math.min(start + this.jumboPartSize, chunk.size));
       const partHash = await sha256Hex(partBlob);
@@ -694,13 +1637,18 @@ function createMountraClient(options) {
 }
 export {
   DEFAULT_S3_MULTIPART_PART_SIZE_BYTES,
+  DownloadHttpError,
+  InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore,
+  IndexedDBDownloadCheckpointStore,
   JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore,
   MAX_S3_MULTIPART_PARTS,
   MIN_S3_MULTIPART_PART_SIZE_BYTES,
   MountraApiError,
   MountraClient,
+  MountraDownloader,
+  MountraFile,
   MountraClient as MountraSDK,
   S3MultipartUploader,
   createMountraClient,