@mountra/mountra-sdk 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @mountra/mountra-sdk
+
+用于浏览器前端接入 Mountra 的 TypeScript SDK。当前提供统一的文件上传工具：普通 chunk 使用签名 PUT，jumbo chunk 使用 S3 Multipart。
+
+## 使用
+
+```ts
+import { createMountraClient } from "@mountra/mountra-sdk";
+
+const mountra = createMountraClient({
+  baseUrl: "https://mountra.example.com",
+  token: "your-bearer-token",
+  workspaceCuid: "workspace-cuid",
+});
+
+const result = await mountra.upload(file, {
+  path: "/documents/report.pdf",
+  // 默认是 1：整个文件作为一个 chunk 上传
+  chunkCount: 1,
+  onProgress: ({ uploadedBytes, totalBytes }) => {
+    console.log(`${uploadedBytes}/${totalBytes}`);
+  },
+});
+
+console.log(result.ino, result.path);
+```
+
+SDK 会先计算文件及每个 chunk 的 SHA-256，然后调用 `/api/upload/prepare`。对返回的每个签名 URL 按 chunk 顺序执行 PUT，最后调用 `/api/upload/finish`。
+
+## Jumbo chunk
+
+尺寸严格大于 128 MiB 的 chunk 会走 S3 Multipart。SDK 不直接绑定某一个 S3 SDK，而是提供 `S3MultipartUploader` 适配器，宿主应用把实际 S3 SDK 的三个操作接入即可：
+
+```ts
+import { S3MultipartUploader } from "@mountra/mountra-sdk";
+
+const s3MultipartUploader = new S3MultipartUploader({
+  bucket: "mountra-bucket",
+  client: {
+    createMultipartUpload: async ({ bucket, key, contentType, signal }) => {
+      const result = await s3.createMultipartUpload({
+        Bucket: bucket,
+        Key: key,
+        ContentType: contentType,
+        signal,
+      });
+      return { uploadId: result.UploadId! };
+    },
+    uploadPart: async ({ bucket, key, uploadId, partNumber, body, signal }) => {
+      const result = await s3.uploadPart({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId,
+        PartNumber: partNumber,
+        Body: body,
+        signal,
+      });
+      return { etag: result.ETag! };
+    },
+    completeMultipartUpload: async ({ bucket, key, uploadId, parts, signal }) => {
+      await s3.completeMultipartUpload({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId,
+        MultipartUpload: { Parts: parts.map(({ partNumber, etag }) => ({ PartNumber: partNumber, ETag: etag })) },
+        signal,
+      });
+    },
+  },
+});
+```
+
+默认每个 S3 part 为 16 MiB，可通过 `jumboPartSize` 调整，但不能小于 S3 要求的 5 MiB。每个成功的 part 都会写入 `localStorage` checkpoint；发生中断后，再次调用 `upload` 或 `resumeUpload` 会跳过已记录且 hash/size 匹配的 part，继续上传剩余 part。S3 Multipart 完成后，SDK 仍会调用 Mountra `/api/upload/finish`，只有两者都成功才清理本地 checkpoint。
+
+传入的 bucket 和凭证必须能够访问 Mountra prepare 返回的 `storage_key` 对应对象存储；SDK 不会把 Mountra 服务端的存储凭证暴露到接口响应中。
+
+`prepareUpload` 会同时返回可序列化的 `context`。客户端应把它和可恢复的文件/blob 引用一起保存到 IndexedDB 等本地存储中：
+
+```ts
+const prepared = await mountra.prepareUpload(file, {
+  path: "/documents/report.pdf",
+  chunkCount: 8,
+  onSessionPrepared: async (context) => {
+    await uploadStore.save(context); // 不能只保存 uploadId
+  },
+});
+
+// 应用重启后恢复同一个文件/blob 和 context
+const status = await mountra.getUploadStatus(prepared.context.uploadId);
+const result = await mountra.resumeUpload(file, prepared.context);
+```
+
+`getUploadStatus` 返回每个 chunk 的 `pending/uploaded` 状态，以及 pending chunk 可直接使用的 PUT 目标。服务端会根据对象存储中的对象重新校验状态，因此客户端不应仅依赖内存中的上传进度。
+
+`chunkCount > 1` 时请求使用 `chunk_method: "fix"`。云端会为每个 chunk 保存独立的 descriptor，并在 status 查询中根据对象存储重新确认上传状态。
+
+## 开发
+
+```bash
+pnpm --dir mountra-sdk install
+pnpm --dir mountra-sdk typecheck
+pnpm --dir mountra-sdk test
+pnpm --dir mountra-sdk build
+```
+
+## 发布到 NPM
+
+先使用拥有 `@mountra` scope 发布权限的账号登录 NPM：
+
+```bash
+npm login
+```
+
+在仓库根目录执行：
+
+```bash
+pnpm publish:sdk
+```
+
+发布脚本会依次执行类型检查、测试和构建，然后发布公开的 `@mountra/mountra-sdk` package。实际发布前可以先预览将要发布的内容：
+
+```bash
+pnpm publish:sdk --dry-run
+```
+
+发布包只包含 `dist/` 和本 README，不包含源码与测试文件。