@seaverse/utils-sdk 0.1.0

package/README.md

@@ -0,0 +1,446 @@
+# @seaverse/utils-sdk
+
+SeaVerse Utils SDK - 通用工具集合，包含文件上传、图片压缩等功能
+
+[![npm version](https://img.shields.io/npm/v/@seaverse/utils-sdk.svg)](https://www.npmjs.com/package/@seaverse/utils-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 功能特性
+
+- 📤 **文件上传** - 预签名 URL 两步上传，安全高效
+- 🖼️ **图片压缩** - 自动压缩到 1080p，可配置质量和尺寸
+- 📊 **上传进度** - 实时进度回调，支持速度和剩余时间计算
+- ✅ **文件验证** - 大小和类型验证
+- ⚡ **TypeScript** - 完整的类型定义
+- 🌍 **环境配置** - 支持多环境切换
+
+## 安装
+
+```bash
+npm install @seaverse/utils-sdk
+# 或
+pnpm add @seaverse/utils-sdk
+```
+
+## 快速开始
+
+### 基础用法
+
+```typescript
+import { UtilsClient } from '@seaverse/utils-sdk';
+
+// 初始化客户端
+const client = new UtilsClient({
+  token: 'your-bearer-token',
+});
+
+// 上传文件
+const file = document.querySelector('input[type="file"]').files[0];
+const result = await client.uploadFile(file);
+
+console.log('CDN URL:', result.cdnUrl);
+console.log('文件大小:', result.fileSize);
+console.log('是否压缩:', result.compressed);
+```
+
+### 带进度回调
+
+```typescript
+const result = await client.uploadFile(file, {
+  onProgress: (progress) => {
+    console.log(`进度: ${progress.percent}%`);
+    console.log(`阶段: ${progress.stage}`);
+    console.log(`速度: ${progress.speed} 字节/秒`);
+    console.log(`剩余时间: ${progress.remainingTime} 秒`);
+  },
+});
+```
+
+### 禁用图片压缩
+
+```typescript
+const result = await client.uploadFile(file, {
+  compress: false, // 禁用压缩
+});
+```
+
+### 自定义压缩配置
+
+```typescript
+const client = new UtilsClient({
+  token: 'your-bearer-token',
+  compress: {
+    enabled: true,
+    maxWidth: 1920,    // 自定义最大宽度
+    maxHeight: 1080,   // 自定义最大高度
+    quality: 0.9,      // 自定义压缩质量
+  },
+});
+```
+
+## API 参考
+
+### UtilsClient
+
+#### 构造函数
+
+```typescript
+new UtilsClient(options: UtilsClientOptions)
+```
+
+**参数:**
+
+- `token` (string, 必需): Bearer Token
+- `baseURL` (string, 可选): API 基础 URL，默认 `https://resource.seaverse.ai`
+- `timeout` (number, 可选): 请求超时(毫秒)，默认 60000
+- `compress` (CompressionConfig, 可选): 图片压缩配置
+
+**CompressionConfig:**
+
+- `enabled` (boolean): 是否启用压缩，默认 `true`
+- `maxWidth` (number): 最大宽度，默认 `1080`
+- `maxHeight` (number): 最大高度，默认 `1080`
+- `quality` (number): 压缩质量 (0-1)，默认 `0.8`
+
+#### uploadFile()
+
+上传文件，自动处理压缩、验证、上传流程。
+
+```typescript
+async uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>
+```
+
+**参数:**
+
+- `file`: 要上传的文件对象
+- `options` (可选):
+  - `onProgress`: 进度回调函数
+  - `compress`: 是否压缩（覆盖全局配置）
+  - `metadata`: 自定义元数据
+
+**返回:**
+
+```typescript
+{
+  fileName: string          // 文件名
+  originalFileName: string  // 原始文件名
+  cdnUrl: string           // CDN 访问 URL
+  objectPath: string       // 存储路径
+  fileSize: number         // 文件大小（字节）
+  originalSize: number     // 原始大小（字节）
+  compressed: boolean      // 是否被压缩
+  contentType: string      // MIME 类型
+  duration: number         // 上传耗时（毫秒）
+  expiresAt: string        // 过期时间
+}
+```
+
+**错误:**
+
+- 抛出 `UtilsAPIError` 异常
+
+**示例:**
+
+```typescript
+try {
+  const result = await client.uploadFile(file, {
+    onProgress: (progress) => {
+      updateProgressBar(progress.percent);
+    },
+  });
+  console.log('上传成功:', result.cdnUrl);
+} catch (error) {
+  if (error instanceof UtilsAPIError) {
+    console.error(`上传失败 [${error.code}]: ${error.message}`);
+  }
+}
+```
+
+#### setToken()
+
+更新 Bearer Token。
+
+```typescript
+setToken(token: string): void
+```
+
+#### setBaseURL()
+
+更新基础 URL。
+
+```typescript
+setBaseURL(baseURL: string): void
+```
+
+#### updateCompressionConfig()
+
+更新压缩配置。
+
+```typescript
+updateCompressionConfig(config: Partial<CompressionConfig>): void
+```
+
+## 工具函数
+
+### validateFile()
+
+验证文件大小和类型。
+
+```typescript
+import { validateFile } from '@seaverse/utils-sdk';
+
+const result = validateFile(file, {
+  maxSize: 10 * 1024 * 1024,  // 10MB
+  allowedTypes: ['image/jpeg', 'image/png'],
+});
+
+if (!result.valid) {
+  console.error('验证失败:', result.errors);
+}
+```
+
+### compressImage()
+
+手动压缩图片。
+
+```typescript
+import { compressImage } from '@seaverse/utils-sdk';
+
+const result = await compressImage(file, {
+  maxWidth: 1920,
+  maxHeight: 1080,
+  quality: 0.8,
+});
+
+console.log('压缩率:', result.compressionRatio);
+console.log('压缩后大小:', result.compressedSize);
+```
+
+### formatBytes()
+
+格式化字节数为可读字符串。
+
+```typescript
+import { formatBytes } from '@seaverse/utils-sdk';
+
+console.log(formatBytes(1024));       // "1 KB"
+console.log(formatBytes(1048576));    // "1 MB"
+console.log(formatBytes(1073741824)); // "1 GB"
+```
+
+## 错误处理
+
+```typescript
+import { UtilsAPIError, ErrorCode } from '@seaverse/utils-sdk';
+
+try {
+  const result = await client.uploadFile(file);
+} catch (error) {
+  if (error instanceof UtilsAPIError) {
+    switch (error.code) {
+      case ErrorCode.FILE_TOO_LARGE:
+        alert('文件太大，请选择小于 100MB 的文件');
+        break;
+      case ErrorCode.INVALID_FILE_TYPE:
+        alert('不支持的文件类型');
+        break;
+      case ErrorCode.NETWORK_ERROR:
+        alert('网络错误，请检查网络连接');
+        break;
+      default:
+        alert(`上传失败: ${error.message}`);
+    }
+  }
+}
+```
+
+## 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `FILE_TOO_LARGE` | 文件大小超过限制 |
+| `INVALID_FILE_TYPE` | 不支持的文件类型 |
+| `PRESIGNED_URL_FAILED` | 获取预签名 URL 失败 |
+| `UPLOAD_FAILED` | 上传失败 |
+| `COMPRESSION_FAILED` | 图片压缩失败 |
+| `NETWORK_ERROR` | 网络错误 |
+| `TIMEOUT` | 请求超时 |
+| `VALIDATION_FAILED` | 文件验证失败 |
+
+## 环境配置
+
+不同环境使用不同的 baseURL：
+
+```typescript
+// 开发环境（默认）
+const client = new UtilsClient({
+  token: devToken,
+  // baseURL 默认为 'https://resource.seaverse.ai'
+});
+
+// 生产环境
+const client = new UtilsClient({
+  baseURL: 'https://resource.sg.seaverse.dev',
+  token: prodToken,
+});
+
+// 本地开发
+const client = new UtilsClient({
+  baseURL: 'http://localhost:8003',
+  token: localToken,
+});
+```
+
+## 与 Auth SDK 集成
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+import { UtilsClient } from '@seaverse/utils-sdk';
+
+// 1. 使用 Auth SDK 登录
+const authClient = new SeaVerseBackendAPIClient({
+  appId: 'your-app-id',
+});
+
+const loginResult = await authClient.login({
+  email: 'user@example.com',
+  password: 'password',
+});
+
+// 2. 使用相同的 token 初始化 Utils SDK
+const utilsClient = new UtilsClient({
+  token: loginResult.token,
+});
+
+// 3. 上传文件
+const result = await utilsClient.uploadFile(file);
+```
+
+## 上传流程说明
+
+SDK 使用预签名 URL 两步上传模式：
+
+```
+1. 获取预签名 URL
+   POST /api/v1/resources/presign-upload
+   → 返回 upload_url 和 cdn_url
+
+2. 上传到 GCS
+   PUT {upload_url}
+   → 直接上传到 Google Cloud Storage
+
+3. 返回 CDN URL
+   使用 cdn_url 访问文件
+```
+
+**优势:**
+
+- ✅ 安全：Token 不暴露给第三方存储
+- ✅ 高效：直接上传到 GCS，无需经过后端
+- ✅ 可靠：GCS 提供高可用性保证
+
+## 图片压缩说明
+
+### 压缩策略
+
+- 最大尺寸: 1080×1080 像素（默认配置）
+- 保持宽高比自动缩放
+- 可配置压缩质量 (0-1)
+- 支持自定义最大宽高（maxWidth、maxHeight）
+
+### 压缩触发条件
+
+只有以下条件同时满足时才会压缩：
+
+1. 文件是图片类型（MIME type 以 `image/` 开头）
+2. 压缩配置启用（`compress.enabled === true`）
+3. 未在上传选项中明确禁用（`options.compress !== false`）
+
+### 跳过压缩
+
+```typescript
+// 方式 1：全局禁用
+const client = new UtilsClient({
+  token: 'xxx',
+  compress: { enabled: false },
+});
+
+// 方式 2：单次上传禁用
+const result = await client.uploadFile(file, {
+  compress: false,
+});
+```
+
+## 常见问题
+
+### Q1: 如何获取 token？
+
+**A**: 通过 `@seaverse/auth-sdk` 登录获取 Bearer Token
+
+### Q2: 支持哪些文件类型？
+
+**A**:
+- **图片**: JPEG, PNG, GIF, WebP
+- **文档**: PDF, TXT, MD
+- **其他**: 根据后端配置而定
+
+### Q3: 上传文件大小限制？
+
+**A**:
+- 默认限制: 100MB
+- 可通过验证规则自定义
+- 图片会自动压缩，减小传输大小
+
+### Q4: 如何处理上传失败？
+
+**A**:
+```typescript
+try {
+  await client.uploadFile(file);
+} catch (error) {
+  if (error instanceof UtilsAPIError) {
+    // 根据错误码处理
+    if (error.code === ErrorCode.NETWORK_ERROR) {
+      // 重试逻辑
+    }
+  }
+}
+```
+
+### Q5: 压缩会影响图片质量吗？
+
+**A**:
+- 默认质量为 0.8，平衡文件大小和画质
+- 可通过 `quality` 参数调整 (0-1)
+- 建议值: 0.7-0.9
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm build
+
+# 开发模式
+pnpm dev
+
+# 类型检查
+pnpm typecheck
+```
+
+## 许可证
+
+MIT © [SeaVerse Team](mailto:support@seaverse.com)
+
+## 更新日志
+
+### v0.1.0 (2026-01-07)
+
+- 🎉 初始版本发布
+- ✨ 支持文件上传（预签名 URL 模式）
+- ✨ 支持图片自动压缩（1080p）
+- ✨ 支持上传进度回调
+- ✨ 支持文件验证
+- ✨ 完整的 TypeScript 类型定义

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+/**
+ * SeaVerse Utils SDK Client
+ */
+import { UtilsClientOptions, UploadOptions, UploadResult, UploadProgress, PresignUploadResponse, CompressionConfig } from './models.js';
+/**
+ * SeaVerse Utils API Client
+ *
+ * 提供文件上传、图片压缩等功能，支持多租户隔离。
+ * 自动处理预签名 URL 上传流程：
+ * 1. 获取预签名 URL
+ * 2. 直接上传到 GCS
+ *
+ * @example
+ * ```typescript
+ * const client = new UtilsClient({
+ *   token: 'your-bearer-token'
+ * });
+ *
+ * const file = document.querySelector('input[type="file"]').files[0];
+ * const result = await client.uploadFile(file, {
+ *   onProgress: (progress) => {
+ *     console.log(`${progress.percent}% - ${progress.stage}`);
+ *   }
+ * });
+ *
+ * console.log('CDN URL:', result.cdnUrl);
+ * ```
+ */
+export declare class UtilsClient {
+    private axios;
+    private compressionConfig;
+    constructor(options: UtilsClientOptions);
+    /**
+     * 上传文件
+     *
+     * 自动处理完整的上传流程：
+     * 1. 文件验证
+     * 2. 图片压缩（如果启用）
+     * 3. 获取预签名 URL
+     * 4. 上传到 GCS
+     *
+     * @param file - 要上传的文件
+     * @param options - 上传选项
+     * @returns 上传结果
+     * @throws {UtilsAPIError} 上传失败时抛出错误
+     *
+     * @example
+     * ```typescript
+     * const result = await client.uploadFile(file, {
+     *   onProgress: (progress) => {
+     *     console.log(`上传进度: ${progress.percent}%`);
+     *   },
+     *   compress: true
+     * });
+     * ```
+     */
+    uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * 获取预签名 URL
+     *
+     * @param contentType - 文件 MIME 类型
+     * @returns 预签名 URL 响应
+     * @throws {UtilsAPIError} 请求失败时抛出错误
+     */
+    getPresignedUrl(contentType: string): Promise<PresignUploadResponse>;
+    /**
+     * 上传文件到预签名 URL
+     *
+     * 使用 XMLHttpRequest 实现，以支持上传进度回调
+     *
+     * @param uploadUrl - 预签名 URL
+     * @param file - 要上传的文件
+     * @param onProgress - 进度回调函数
+     * @throws {UtilsAPIError} 上传失败时抛出错误
+     */
+    uploadToPresignedUrl(uploadUrl: string, file: File, onProgress?: (progress: UploadProgress) => void): Promise<void>;
+    /**
+     * 更新 Bearer Token
+     *
+     * @param token - 新的 Bearer Token
+     */
+    setToken(token: string): void;
+    /**
+     * 更新基础 URL
+     *
+     * @param baseURL - 新的基础 URL
+     */
+    setBaseURL(baseURL: string): void;
+    /**
+     * 更新压缩配置
+     *
+     * @param config - 新的压缩配置
+     */
+    updateCompressionConfig(config: Partial<CompressionConfig>): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,cAAc,EAEd,qBAAqB,EACrB,iBAAiB,EAGlB,MAAM,aAAa,CAAC;AAUrB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,iBAAiB,CAA8B;gBAE3C,OAAO,EAAE,kBAAkB;IA4BvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IA8F5E;;;;;;OAMG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAgC1E;;;;;;;;;OASG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,IAAI,EACV,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAC9C,OAAO,CAAC,IAAI,CAAC;IAgEhB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;CAMlE"}