fsd-oss 0.14.1 → 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Xingchen https://github.com/liangxingchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, destribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,39 +1,66 @@
 # fsd-oss
 
-FSD OSS文件读写适配器。
+FSD 阿里云 OSS 文件存储适配器 - 提供对阿里云 OSS 对象存储的读写访问。
 
-```js
-const FSD = require('fsd');
-const OSSAdapter = require('fsd-oss');
+[![npm version](https://badge.fury.io/js/fsd-oss.svg)](https://www.npmjs.com/package/fsd-oss)
 
-const adapter = new OSSAdapter(config);
-const fsd = FSD({ adapter: adapter });
+## 概述
 
-let file = fsd('/test.txt');
+`fsd-oss` 是 `fsd` 核心库的阿里云 OSS 适配器，提供完整的对象存储操作能力。
 
-let content = await fsd.read();
+### 核心特性
 
+- ✅ 完整的文件 CRUD 操作
+- ✅ 分段上传（大文件优化）
+- ✅ STS 角色扮演（边缘上传）
+- ✅ 上传回调通知
+- ✅ 自定义 OSS 客户端
+- ✅ 缩略图支持
+
+## 安装
+
+```bash
+npm install fsd-oss
+```
+
+## 配置
+
+```typescript
+import FSD from 'fsd';
+import OSSAdapter from 'fsd-oss';
+
+// 创建适配器
+const adapter = new OSSAdapter({
+  accessKeyId: 'your-access-key-id',        // 必需：OSS 访问凭证
+  accessKeySecret: 'your-access-key-secret', // 必需：OSS 访问凭证
+  region: 'oss-cn-hangzhou',                // 必需：OSS 区域
+  bucket: 'your-bucket-name'                // 可选：Bucket 名称
+});
+
+// 创建 FSD 实例
+const fsd = FSD({ adapter });
 ```
 
-FSD 文档： https://github.com/liangxingchen/fsd
+### 配置选项说明
 
-适配器初始化选项：
+| 选项 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `accessKeyId` | string | 是 | - | OSS 访问凭证 |
+| `accessKeySecret` | string | 是 | - | OSS 访问凭证 |
+| `region` | string | 是 | - | OSS 区域（如 oss-cn-hangzhou） |
+| `bucket` | string | 否 | - | Bucket 名称（也可在 path 中指定） |
+| `root` | string | 否 | '/' | 存储根路径 |
+| `urlPrefix` | string | 否 | - | URL 前缀，用于生成访问链接 |
+| `publicRead` | boolean | 否 | false | 是否公共读，控制生成的 URL 是否需要签名 |
+| `internal` | boolean | 否 | false | 是否使用内网访问，与应用在同一区域时更快且免费 |
+| `secure` | boolean | 否 | true | 是否使用 HTTPS |
+| `timeout` | number | 否 | - | 请求超时时间（毫秒） |
+| `accountId` | string | 否 | - | STS 角色扮演：阿里云账号 ID |
+| `roleName` | string | 否 | - | STS 角色扮演：角色名称 |
+| `callbackUrl` | string | 否 | - | 上传回调 URL，上传完成后 OSS 会调用此接口 |
+| `thumbs` | object | 否 | - | 缩略图配置，key 为缩略图名称，value 为 OSS 处理参数 |
 
-| 选项              | 类型               | 必须   | 说明                           |
-| --------------- | ---------------- | ---- | ---------------------------- |
-| root            | string           |      | 以OSS子目录作为存储根路径，例如 '/uploads' |
-| urlPrefix       | string           |      | URL前缀，用于生成下载链接               |
-| publicRead      | boolean          |      | bucket是否允许公共读               |
-| accessKeyId     | string           | Yes  | OSS访问KEY                     |
-| accessKeySecret | string           | Yes  | OSS访问秘钥                      |
-| bucket          | string           |      |                              |
-| region          | string           |      |                              |
-| internal        | boolean          |      |                              |
-| secure          | boolean          |      |                              |
-| timeout         | string \| number |      |                              |
-| accountId | string | | 阿里云账号，用于边缘上传生成STS角色扮演令牌 |
-| roleName | string | | 阿里云角色名，用于边缘上传生成STS角色扮演令牌 |
-| callbackUrl | string | | 边缘上传后的回调地址 |
 
-OSS 相关参数设置参考 https://github.com/ali-sdk/ali-oss#ossoptions
+## License
 
+MIT

package/index.d.ts

@@ -1,78 +1,525 @@
 import { Adapter } from 'fsd';
 
+/**
+ * OSSAdapter 配置选项
+ *
+ * 阿里云 OSS 对象存储适配器的初始化配置。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new OSSAdapter({
+ *   accessKeyId: 'your-access-key-id',
+ *   accessKeySecret: 'your-access-key-secret',
+ *   region: 'oss-cn-hangzhou',
+ *   bucket: 'my-bucket'
+ * });
+ * ```
+ */
 export interface OSSAdapterOptions {
+  /**
+   * OSS 存储根路径（可选）
+   *
+   * 以 OSS 子目录作为存储根路径。
+   * 所有文件操作都会在此路径下进行。
+   *
+   * @example
+   * ```typescript
+   * root: '/uploads'
+   * // 文件路径: '/uploads/file.txt'
+   * // OSS 实际路径: 'uploads/file.txt'
+   * ```
+   */
   root?: string;
+
+  /**
+   * URL 前缀（可选）
+   *
+   * 用于生成访问链接时添加前缀。
+   * 通常配合 CDN 或反向代理使用。
+   *
+   * @example
+   * ```typescript
+   * urlPrefix: 'https://cdn.example.com',
+   * // file.createUrl() 返回: https://cdn.example.com/uploads/file.txt
+   * ```
+   */
   urlPrefix?: string;
+
   /**
-   * 是否公开读，默认为false
+   * 是否公共读（可选）
+   *
+   * 控制生成的 URL 是否需要签名访问。
+   *
+   * - `true`: 公共 Bucket，生成直接访问 URL（无需签名）
+   * - `false`: 私有 Bucket，生成带签名的临时 URL（默认值）
+   *
+   * @example
+   * ```typescript
+   * // 公共访问
+   * publicRead: true,
+   * // URL: https://bucket.oss-cn-hangzhou.aliyuncs.com/file.jpg
+   *
+   * // 私有访问
+   * publicRead: false,
+   * // URL: https://bucket.oss-cn-hangzhou.aliyuncs.com/file.jpg?OSSAccessKeyId=...&Expires=...
+   * ```
    */
   publicRead?: boolean;
-  // 以下为OSS驱动配置
+
+  /**
+   * OSS 访问 Key ID（必需）
+   *
+   * 阿里云 OSS 的 Access Key ID。
+   *
+   * @example
+   * ```typescript
+   * accessKeyId: 'LTAI5txxxxxxxxxxxxx'
+   * ```
+   */
   accessKeyId: string;
+
+  /**
+   * OSS 访问 Key Secret（必需）
+   *
+   * 阿里云 OSS 的 Access Key Secret。
+   *
+   * @example
+   * ```typescript
+   * accessKeySecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+   * ```
+   *
+   * @remarks
+   * 请妥善保管此密钥，不要提交到代码仓库。
+   * 建议使用环境变量存储。
+   */
   accessKeySecret: string;
-  bucket: string;
+
+  /**
+   * OSS Bucket 名称（可选）
+   *
+   * 如果不指定，需要在上传时在 path 中包含 bucket 名称。
+   *
+   * @example
+   * ```typescript
+   * bucket: 'my-bucket',
+   * // 文件路径: '/uploads/file.txt'
+   * // OSS 实际路径: 'my-bucket/uploads/file.txt'
+   * ```
+   */
+  bucket?: string;
+
+  /**
+   * OSS 区域代码（必需）
+   *
+   * 阿里云 OSS 的区域代码，如 'oss-cn-hangzhou'。
+   *
+   * @example
+   * ```typescript
+   * region: 'oss-cn-hangzhou',  // 华东1（杭州）
+   * region: 'oss-cn-shanghai', // 华东2（上海）
+   * region: 'oss-us-west-1'   // 美西1（硅谷）
+   * ```
+   *
+   * @remarks
+   * 常见区域代码：
+   * - oss-cn-hangzhou: 华东1（杭州）
+   * - oss-cn-shanghai: 华东2（上海）
+   * - oss-cn-beijing: 华北2（北京）
+   * - oss-cn-shenzhen: 华南1（深圳）
+   * - oss-cn-hongkong: 香港
+   * - oss-us-west-1: 美西1（硅谷）
+   */
   region: string;
+
+  /**
+   * 是否内网访问（可选）
+   *
+   * - `true`: 使用内网地址（更快且免费）
+   * - `false`: 使用公网地址（默认值）
+   *
+   * @example
+   * ```typescript
+   * // 如果应用和 OSS 在同一区域，使用内网
+   * internal: true,
+   * // 实际 endpoint: bucket.oss-cn-hangzhou-internal.aliyuncs.com
+   * ```
+   */
   internal?: boolean;
+
+  /**
+   * 是否使用 HTTPS（可选）
+   *
+   * - `true`: 使用 HTTPS（默认值）
+   * - `false`: 使用 HTTP
+   *
+   * @example
+   * ```typescript
+   * secure: true,   // https://bucket.oss-cn-hangzhou.aliyuncs.com
+   * secure: false,  // http://bucket.oss-cn-hangzhou.aliyuncs.com
+   * ```
+   */
   secure?: boolean;
+
+  /**
+   * 请求超时时间（可选）
+   *
+   * 单位：毫秒（数字）或秒（字符串）
+   *
+   * @example
+   * ```typescript
+   * timeout: 60000,    // 60 秒（毫秒）
+   * timeout: '60s'     // 60 秒（字符串）
+   * timeout: 120000    // 120 秒
+   * ```
+   */
   timeout?: string | number;
-  // 角色扮演
+
+  /**
+   * 阿里云账号 ID（可选）
+   *
+   * 用于 STS 角色扮演，生成边缘上传的临时凭证。
+   *
+   * @example
+   * ```typescript
+   * accountId: '1234567890123456',
+   * roleName: 'AliyunOSSRole'
+   * ```
+   *
+   * @remarks
+   * 当同时提供 `accountId` 和 `roleName` 时，适配器会生成 STS 临时凭证。
+   * 临时凭证用于客户端直接上传到 OSS，无需通过服务器中转。
+   */
   accountId?: string;
+
+  /**
+   * 阿里云角色名称（可选）
+   *
+   * 用于 STS 角色扮演，配合 `accountId` 使用。
+   *
+   * @example
+   * ```typescript
+   * accountId: '1234567890123456',
+   * roleName: 'AliyunOSSRole'
+   * ```
+   */
   roleName?: string;
-  callbackUrl?: string; // 边缘上传回调地址
+
   /**
-   * 缩略图配置
+   * 上传回调 URL（可选）
+   *
+   * 文件上传完成后，OSS 会调用此 URL 通知应用。
+   *
+   * @example
+   * ```typescript
+   * callbackUrl: 'https://api.example.com/oss/callback'
+   * ```
+   *
+   * @remarks
+   * 回调 body 包含：
+   * - bucket: Bucket 名称
+   * - path: 文件路径
+   * - etag: 文件 ETag
+   * - size: 文件大小
+   * - mimeType: MIME 类型
+   * - imageInfo: 图片信息（如果是图片）
+   */
+  callbackUrl?: string;
+
+  /**
+   * 缩略图配置（可选）
+   *
+   * 配置缩略图规格和样式。
+   *
+   * @example
+   * ```typescript
+   * thumbs: {
+   *   'small': '?x-oss-process=style/small',
+   *   'medium': '?x-oss-process=style/medium',
+   *   'large': '?x-oss-process=style/large'
+   * }
+   * ```
+   *
+   * @remarks
+   * 缩略图通过 OSS 图片处理服务生成。
+   * 使用时在 `createUrl()` 中指定 thumb 选项。
    */
   thumbs?: {
-    // name -> ?x-oss-process=style/stylename
+    /**
+     * 缩略图规格名
+     *
+     * 值为 OSS 图片处理参数。
+     * 常用：
+     * - `?x-oss-process=image/resize,w_100`: 调整宽度到 100px
+     * - `?x-oss-process=image/crop,w_100,h_100`: 裁剪 100x100
+     * - `?x-oss-process=style/name`: 使用命名样式
+     */
     [name: string]: string;
   };
 }
 
+/**
+ * 上传凭证
+ *
+ * 包含临时访问凭证的返回值。
+ *
+ * @example
+ * ```typescript
+ * {
+ *   auth: {
+ *     accessKeyId: 'STS.xxxxxxxxxxxxxx',
+ *     accessKeySecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+ *     stsToken: 'CAESxxxx...',
+ *     bucket: 'my-bucket',
+ *     endpoint: 'oss-cn-hangzhou.aliyuncs.com'
+ *   },
+ *   path: '/uploads/file.jpg',
+ *   expiration: 17001234567890,
+ *   callback: undefined
+ * }
+ * ```
+ */
 export interface UploadToken {
+  /**
+   * 认证信息
+   *
+   * 包含临时的访问密钥和 STS Token。
+   */
   auth: {
+    /**
+     * 临时 Access Key ID
+     */
     accessKeyId: string;
+
+    /**
+     * 临时 Access Key Secret
+     */
     accessKeySecret: string;
+
+    /**
+     * STS 临时 Token
+     */
     stsToken: string;
+
+    /**
+     * Bucket 名称
+     */
     bucket: string;
+
+    /**
+     * OSS 访问地址
+     */
     endpoint: string;
   };
+
+  /**
+   * 上传目标路径
+   *
+   * 文件在 OSS 中的完整路径。
+   */
   path: string;
+
+  /**
+   * 凭证过期时间（Unix 时间戳，秒）
+   *
+   * 过期后凭证将失效。
+   */
   expiration: number;
+
+  /**
+   * 回调数据（可选）
+   *
+   * 如果配置了 `callbackUrl`，此项存在。
+   */
   callback?: any;
 }
 
+/**
+ * 带自动刷新的上传凭证
+ *
+ * 包含自动刷新 STS Token 的上传凭证。
+ *
+ * @example
+ * ```typescript
+ * {
+ *   auth: {
+ *     accessKeyId: 'STS.xxxxxxxxxxxxxx',
+ *     accessKeySecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+ *     stsToken: 'CAESxxxx...',
+ *     bucket: 'my-bucket',
+ *     endpoint: 'oss-cn-hangzhou.aliyuncs.com',
+ *     refreshSTSToken: [Function: refresh]
+ *   },
+ *   path: '/uploads/file.jpg',
+ *   expiration: 17001234567890
+ * }
+ * ```
+ *
+ * @remarks
+ * 当凭证即将过期时，调用 `refreshSTSToken()` 获取新的临时凭证。
+ */
 export interface UploadTokenWithAutoRefresh {
+  /**
+   * 认证信息
+   */
   auth: {
+    /**
+     * 临时 Access Key ID
+     */
     accessKeyId: string;
+
+    /**
+     * 临时 Access Key Secret
+     */
     accessKeySecret: string;
+
+    /**
+     * STS 临时 Token
+     */
     stsToken: string;
+
+    /**
+     * Bucket 名称
+     */
     bucket: string;
+
+    /**
+     * OSS 访问地址
+     */
     endpoint: string;
+
+    /**
+     * 自动刷新 STS Token 的函数
+     *
+     * 调用此函数获取新的临时凭证。
+     *
+     * @example
+     * ```typescript
+     * const newToken = await auth.refreshSTSToken();
+     * console.log(newToken.stsToken);
+     * ```
+     */
     refreshSTSToken: () => Promise<{
       accessKeyId: string;
       accessKeySecret: string;
       stsToken: string;
     }>;
   };
+
+  /**
+   * 上传目标路径
+   */
   path: string;
+
+  /**
+   * 凭证过期时间
+   */
   expiration: number;
+
+  /**
+   * 回调数据（可选）
+   */
   callback?: any;
 }
 
-export default class OSSAdpter extends Adapter<OSSAdapterOptions> {
+/**
+ * 阿里云 OSS 适配器
+ *
+ * 提供对阿里云 OSS 对象存储的访问能力。
+ *
+ * @remarks
+ * ### 核心特性
+ * - 完整的文件 CRUD 操作（create, read, update, delete）
+ * - 分段上传（大文件优化）
+ * - STS 角色扮演（边缘上传）
+ * - 上传回调通知
+ * - 缩略图支持
+ *
+ * ### 不支持的操作
+ * - `mkdir()` - OSS 无目录概念
+ * - `createReadStream({ start })` - 不支持 start 选项
+ *
+ * ### 已废弃的选项
+ * - `endpoint` - 已废弃，使用 `region/[internal]/[secure]` 代替
+ *
+ * ### 自定义 OSS 客户端
+ * - 内部使用 `SimpleOSSClient` 封装阿里云 OSS API
+ *
+ * ### STS 角色扮演
+ * - 配置 `accountId` + `roleName` 时自动启用
+ * - 用于客户端直接上传到 OSS（边缘上传）
+ *
+ * @example
+ * ```typescript
+ * import OSSAdapter from 'fsd-oss';
+ * import FSD from 'fsd';
+ *
+ * // 基础配置
+ * const adapter = new OSSAdapter({
+ *   accessKeyId: process.env.OSS_ACCESS_KEY_ID,
+ *   accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
+ *   region: process.env.OSS_REGION,
+ *   bucket: process.env.OSS_BUCKET
+ * });
+ *
+ * const fsd = FSD({ adapter });
+ *
+ * // 上传文件
+ * await fsd('/uploads/file.jpg').write(buffer);
+ *
+ * // 生成访问 URL
+ * const url = await fsd('/uploads/file.jpg').createUrl({ expires: 3600 });
+ * ```
+ */
+export default class OSSAdapter extends Adapter<OSSAdapterOptions> {
   /**
    * 创建上传凭证
-   * @param {string} path 文件路径
-   * @param {any} [meta] 文件元信息
-   * @param {number} [durationSeconds] 上传凭证有效期，单位秒, 默认 3600
+   *
+   * 生成用于客户端直接上传到 OSS 的临时凭证。
+   *
+   * @param path - 文件路径
+   * @param meta - 文件元数据（可选）
+   * @param durationSeconds - 凭证有效期（秒），默认 3600（1 小时）
+   * @returns 上传凭证对象
+   *
+   * @example
+   * ```typescript
+   * // 生成 1 小时有效的上传凭证
+   * const token = await adapter.createUploadToken(
+   *   '/uploads/photo.jpg',
+   *   { contentType: 'image/jpeg' },
+   *   3600
+   * );
+   *
+   * // 将 token 发送给前端
+   * res.json({ uploadToken: token });
+   * ```
+   *
+   * @remarks
+   * 如果配置了 `accountId` 和 `roleName`，会生成 STS 临时凭证。
    */
   createUploadToken: (path: string, meta?: any, durationSeconds?: number) => Promise<UploadToken>;
 
   /**
    * 创建带自动刷新的上传凭证
-   * @param {string} path 文件路径
-   * @param {any} [meta] 文件元信息
-   * @param {number} [durationSeconds] 上传凭证有效期，单位秒, 默认 3600
+   *
+   * 生成支持自动刷新 STS Token 的上传凭证。
+   *
+   * @param path - 文件路径
+   * @param meta - 文件元数据（可选）
+   * @param durationSeconds - 凭证有效期（秒），默认 3600（1 小时）
+   * @returns 带刷新功能的上传凭证对象
+   *
+   * @example
+   * ```typescript
+   * const token = await adapter.createUploadTokenWithAutoRefresh(
+   *   '/uploads/large-video.mp4',
+   *   { contentType: 'video/mp4' },
+   *   3600
+   * );
+   *
+   * // 当凭证快过期时，自动刷新
+   * const newAuth = await token.auth.refreshSTSToken();
+   * ```
    */
   createUploadTokenWithAutoRefresh: (
     path: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fsd-oss",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Aliyun OSS adapter for fsd",
   "main": "lib/index.js",
   "types": "index.d.ts",
@@ -9,11 +9,15 @@
     "prepublish": "npm run build"
   },
   "repository": "https://github.com/liangxingchen/fsd/tree/master/packages/fsd-oss",
-  "author": "Liang <liang@miaomo.cc> (https://github.com/liangxingchen)",
+  "author": {
+    "name": "Liang",
+    "email": "liang@miaomo.cn",
+    "url": "https://github.com/liangxingchen"
+  },
   "license": "MIT",
   "dependencies": {
     "@alicloud/pop-core": "^1.8.0",
-    "akita": "^1.1.0",
+    "akita": "^1.2.0",
     "async": "*",
     "crypto-js": "^4.2.0",
     "debug": "^4.4.3",
@@ -21,5 +25,6 @@
     "minimatch": "^9.0.5",
     "slash": "^3.0.0",
     "xml2js": "^0.6.2"
-  }
+  },
+  "gitHead": "ea754919fb95b49deffd529b5c01c66da0dc08f9"
 }