@mountra/mountra-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0 - 2026-08-19
+
+### Added
+
+- Added streaming browser downloads using the File System Access API, including a save-location picker and incremental writes.
+- Added IndexedDB-backed download checkpoints, automatic retry, Range-based resume, and resumable downloads after refresh or network interruption.
+- Added multi-chunk export metadata with per-chunk signed URLs and sequential client-side assembly when File System Access is available.
+- Added download progress callbacks with total size, downloaded bytes, one-second-window speed, elapsed time, retry count, and remaining-time estimation.
+- Added the `MountraFile` resource API:
+  - `client.file({ wsid, path })`
+  - `client.file({ wsid, ino })`
+  - `file.export()`, `file.download()`, and `file.resume()`
+
+### Changed
+
+- `exportFile` responses now include the complete file size and, for multi-chunk files, the ordered chunk export URLs.
+- Existing parameter-based upload and download APIs remain available for compatibility.

package/README.md

@@ -1,6 +1,6 @@
 # @mountra/mountra-sdk
 
-用于浏览器前端接入 Mountra 的 TypeScript SDK。当前提供统一的文件上传工具：普通 chunk 使用签名 PUT，jumbo chunk 使用 S3 Multipart。
+用于浏览器前端接入 Mountra 的 TypeScript SDK。提供文件上传、流式下载、断点续传和多 chunk 客户端组装。
 
 ## 使用
 
@@ -94,6 +94,65 @@ const result = await mountra.resumeUpload(file, prepared.context);
 
 `chunkCount > 1` 时请求使用 `chunk_method: "fix"`。云端会为每个 chunk 保存独立的 descriptor，并在 status 查询中根据对象存储重新确认上传状态。
 
+## 下载
+
+文件操作也可以使用资源对象风格。`path` 和 `ino` 必须二选一；`wsid` 是
+`workspaceId` 的简写。未在对象中提供 workspace 时，会使用创建
+`MountraClient` 时配置的 workspace：
+
+```ts
+const file = mountra.file({
+  wsid: 17,
+  path: "/documents/report.pdf",
+});
+
+const exported = await file.export();
+await file.download({
+  downloadFilename: "report.pdf",
+  onProgress: console.log,
+});
+
+// 页面刷新后，自动选择这个文件最新的可恢复下载 checkpoint
+await file.resume();
+```
+
+也可以通过 inode 定位：
+
+```ts
+const file = mountra.file({ ino: "12345" });
+await file.download();
+```
+
+`file.export()`、`file.download()` 和 `file.resume()` 会始终使用创建对象
+时确定的文件身份，行为参数只能通过各方法的 options 传入。
+
+`exportFile` 返回完整文件大小 `size`。多 chunk 文件还会返回按顺序排列的 `chunks`，每个 chunk 都包含独立的签名 URL；`url` 始终是服务端顺序组装后的完整文件 URL。
+
+```ts
+const result = await mountra.downloadFile({
+  path: "/documents/report.pdf",
+  downloadFilename: "report.pdf",
+  onProgress: ({ downloadedBytes, totalBytes, speedBytesPerSecond, estimatedRemainingSeconds }) => {
+    console.log({ downloadedBytes, totalBytes, speedBytesPerSecond, estimatedRemainingSeconds });
+  },
+});
+```
+
+在支持 File System Access API 的 Chromium 浏览器中，SDK 会先调用 `showSaveFilePicker`，随后使用 `ReadableStream` 将数据直接写入用户选择的文件。多 chunk 文件优先逐个下载 chunk 并按顺序追加；其他浏览器使用服务端组装 URL 并返回 Blob。
+
+下载进度会从 streaming response 实际写入的字节数统计，速度使用最近 1 秒窗口计算。网络错误和常见临时 HTTP 错误默认重试 3 次，可通过 `maxRetries`、`retryDelayMs` 和 `AbortSignal` 调整。
+
+FSA 下载的中间状态默认保存到本地 IndexedDB，包括 chunk 偏移、已写入字节数以及可持久化的文件句柄。刷新页面后可以列出并恢复任务：
+
+```ts
+const pending = await mountra.listResumableDownloads();
+if (pending[0]) {
+  await mountra.resumeDownload(pending[0].key, { onProgress: console.log });
+}
+```
+
+可以通过 `downloadCheckpointStore` 注入自己的 `DownloadCheckpointStore`（测试时可使用 `InMemoryDownloadCheckpointStore`）。SDK 不会把短期签名 URL 写入 checkpoint；恢复时会重新请求 export URL。
+
 ## 开发
 
 ```bash
@@ -123,4 +182,5 @@ pnpm publish:sdk
 pnpm publish:sdk --dry-run
 ```
 
-发布包只包含 `dist/` 和本 README，不包含源码与测试文件。
+发布脚本默认使用 `https://registry.npmjs.org/`，如需发布到其他 registry，设置
+`NPM_REGISTRY` 环境变量。发布包包含 `dist/`、README 和 CHANGELOG，不包含源码与测试文件。