@lhy-meta-server/meta-oss 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meta-workspace
+
+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, distribute, 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,3 +1,378 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @lhy-meta-server/meta-oss
+
+面向 Bun 与 Node.js 的生产级对象存储抽象。一套 API 同时支持本地文件系统与阿里云 OSS，并可通过适配器以极少代码接入任意第三方对象存储；附带 Elysia 注入插件。
+
+- **统一抽象**：业务只依赖 `ObjectStorage`，切换后端只需更换 `driver`。
+- **内置本地存储**：原子写入、路径穿越与符号链接防护、分片上传、HMAC 签名 URL。
+- **零配置 ali-oss**：直接传入 ali-oss 客户端实例即可，本包不依赖 `ali-oss`。
+- **生产可靠性**：超时、取消、指数退避重试、并发控制、上传大小/MIME/扩展名限制、稳定错误码。
+- **可观测**：结构化事件、重试事件与进程内指标，事件中不包含凭据、签名或签名 URL。
+- **运行时兼容**：Bun ≥ 1.3、Node.js ≥ 20，纯 ESM，附带完整类型声明。
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [Elysia 集成](#elysia-集成)
+- [本地文件系统](#本地文件系统)
+- [阿里云 OSS](#阿里云-oss)
+- [接入其他对象存储](#接入其他对象存储)
+- [上传策略与安全](#上传策略与安全)
+- [错误处理](#错误处理)
+- [API](#api)
+- [可观测性](#可观测性)
+- [测试](#测试)
+- [License](#license)
+
+## 安装
+
+```bash
+bun add @lhy-meta-server/meta-oss
+# 或
+npm install @lhy-meta-server/meta-oss
+```
+
+按需安装可选依赖：
+
+```bash
+bun add elysia     # 使用 Elysia 插件时
+bun add ali-oss    # 使用阿里云 OSS 时
+```
+
+## 快速开始
+
+```ts
+import { ObjectStorage, createObjectKey } from '@lhy-meta-server/meta-oss'
+import { FileSystemDriver } from '@lhy-meta-server/meta-oss/filesystem'
+
+const storage = new ObjectStorage({
+  driver: new FileSystemDriver({ root: './storage' }),
+  upload: { maxSize: 10 * 1024 * 1024, allowedContentTypes: ['image/*', 'application/pdf'] },
+})
+
+const key = createObjectKey('头像.png', { directory: 'avatars' })
+// avatars/2026/10/13/1b9d...e2.png
+
+await storage.put(key, file) // File / Blob / Uint8Array / string / ReadableStream / Node.js Readable
+const text = await storage.getText('notes/readme.txt')
+const { info, body } = await storage.get(key) // body 为 Web ReadableStream
+await storage.delete(key)
+```
+
+## Elysia 集成
+
+插件只通过 `decorate` 注入服务并管理生命周期，**不注册任何路由**，路由与鉴权由业务自行实现。
+
+```ts
+import { Elysia, t } from 'elysia'
+import { oss } from '@lhy-meta-server/meta-oss/elysia'
+
+const app = new Elysia()
+  .use(oss({ storage }))
+  .post('/avatars', async ({ oss, body }) => oss.put(`avatars/${crypto.randomUUID()}.png`, body.file), {
+    body: t.Object({ file: t.File() }),
+  })
+  .get('/files/*', async ({ oss, params, set }) => {
+    const { info, body } = await oss.get(params['*'])
+    set.headers['content-type'] = info.contentType
+    return new Response(body)
+  })
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `storage` | `ObjectStorage` | 必填 | 注入的服务实例 |
+| `propertyName` | `string` | `'oss'` | Context 中的属性名 |
+| `name` | `string` | `@lhy-meta-server/meta-oss:<propertyName>` | 插件去重名称 |
+| `closeOnStop` | `boolean` | `true` | 应用停止时关闭存储 |
+
+同一应用可注册多个存储，只需使用不同的 `propertyName`：
+
+```ts
+app.use(oss({ storage: publicStorage })).use(oss({ storage: archiveStorage, propertyName: 'archive' }))
+```
+
+## 本地文件系统
+
+```ts
+import { FileSystemDriver } from '@lhy-meta-server/meta-oss/filesystem'
+
+const driver = new FileSystemDriver({
+  root: '/data/oss',
+  signing: { secret: config.ossSigningSecret, baseUrl: 'https://api.example.com/files' },
+})
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `root` | `string` | 必填 | 存储根目录，不存在时自动创建 |
+| `signing.secret` | `string` | — | HMAC-SHA256 密钥，至少 32 个字符 |
+| `signing.baseUrl` | `string` | — | 签名 URL 的基础地址 |
+| `directoryMode` | `number` | `0o750` | 新建目录权限 |
+| `fileMode` | `number` | `0o640` | 新建文件权限 |
+| `multipartTtl` | `number` | 24 小时 | 未完成分片会话的保留毫秒数 |
+| `temporaryTtl` | `number` | 1 小时 | 崩溃残留临时文件的保留毫秒数，初始化时清理；应大于单次写入最长耗时 |
+| `durable` | `boolean` | `true` | 是否对文件与目录 `fsync`；关闭可提升吞吐，但断电可能丢失最近写入 |
+
+实现要点：
+
+- **原子写入**：内容先写入 `.meta-oss/tmp` 并 `fsync`，再原子 `rename`；`overwrite: false` 时使用 `link` 原子占位，不存在竞态覆盖。提交后同步父目录（Windows 等不支持目录 `fsync` 的平台自动跳过）。
+- **内容与元数据一致**：元数据以内容文件的 inode 命名，并在内容提交前落盘。崩溃或并发写入同一键时，读到的内容、ETag 与元数据总是来自同一次写入。
+- **读取一致**：`get` / `head` 先打开文件句柄再读取状态与元数据；句柄打开后对象被删除或覆盖，本次读取仍返回打开时刻的完整内容。
+- **路径安全**：拒绝 `..`、绝对路径、盘符、反斜杠、控制字符、Windows 保留名，并在解析真实路径后再次确认未逃逸根目录；打开文件后以 inode 复核，消除检查与打开之间被替换为符号链接的竞态。
+- **增量列举**：按目录逐层有序遍历，凑满一页即停止；设置分隔符时不展开被折叠的目录。每页只读取当前页对象的描述信息。
+- **资源回收**：初始化时清理过期临时文件；新建分片会话时清理过期会话；取消写入时立即终止源流并删除临时文件。孤立元数据可在低峰期调用 `driver.cleanup()` 回收。
+- **Windows**：被读取中的文件无法被替换，覆盖写入会短暂退避重试（约 1 秒），仍失败时返回可重试的 `BACKEND`；删除被读取中的文件返回 `ACCESS_DENIED`。
+- **文件系统要求**：`overwrite: false` 依赖硬链接，FAT 与部分网络文件系统不支持。
+
+```ts
+// 例如每天凌晨回收孤立元数据
+const { temporary, metadata } = await driver.cleanup()
+```
+
+### 本地签名 URL
+
+插件不提供路由。签发后，在业务自建的路由中调用 `verifyUrl` 完成鉴权：
+
+```ts
+const url = await storage.signUrl('reports/q3.pdf', { expiresIn: 300, responseContentDisposition: 'attachment' })
+
+app.get('/files/*', async ({ oss, request, set }) => {
+  const { key, responseContentDisposition } = oss.verifyUrl({ url: request.url, method: request.method })
+  const { info, body } = await oss.get(key)
+  set.headers['content-type'] = info.contentType
+  if (responseContentDisposition) set.headers['content-disposition'] = responseContentDisposition
+  return new Response(body)
+})
+```
+
+签名覆盖方法、对象键、过期时间、`Content-Type` 与 `Content-Disposition`，并使用常量时间比较。
+
+## 阿里云 OSS
+
+本包不依赖 `ali-oss`。业务自行安装并创建客户端，适配器只调用其稳定方法，凭据不会被读取或记录。
+
+```ts
+import OSS from 'ali-oss'
+import { ObjectStorage } from '@lhy-meta-server/meta-oss'
+import { AliOssDriver } from '@lhy-meta-server/meta-oss/ali-oss'
+
+const storage = new ObjectStorage({
+  driver: new AliOssDriver({
+    client: new OSS({ region: 'oss-cn-hangzhou', bucket: 'my-bucket', accessKeyId, accessKeySecret }),
+  }),
+})
+```
+
+| 选项 | 类型 | 说明 |
+| --- | --- | --- |
+| `client` | `AliOssClient` | ali-oss 客户端实例（必填） |
+| `serverSideEncryption` | `string` | 服务器端加密算法，如 `AES256`、`KMS` |
+| `storageClass` | `string` | 存储类型，如 `Standard`、`IA`、`Archive` |
+| `bufferThreshold` | `number` | 8 MiB | 不超过该大小的内容整体上传（可重试），更大的内容流式上传，内存占用恒定 |
+
+能力映射：
+
+| 服务 API | ali-oss 调用 |
+| --- | --- |
+| `put` | 不超过 `bufferThreshold` 的已知大小内容用 `put`；更大的内容（含 `Blob`）与流用 `putStream`，取消时销毁上传流；超过服务层 `multipartThreshold` 时自动分片 |
+| `get` | `getStream`，范围读取使用 `Range` 头；打开阶段被取消时销毁响应流 |
+| `head` / `exists` | `head` 获取类型与元数据；SDK 提供 `getObjectMeta` 时用其获取准确大小与 ETag（不受 gzip 影响） |
+| `deleteMany` | `deleteMulti`（每批 1000 个） |
+| `copy` / `move` | 服务端 `copy`，`overwrite: false` 时使用 `x-oss-forbid-overwrite` |
+| `list` | `list`，游标映射为 `marker` |
+| `signUrl` | 优先 `asyncSignatureUrl`（支持 STS 刷新），回退 `signatureUrl` |
+| 分片上传 | `initMultipartUpload` / `uploadPart` / `completeMultipartUpload` / `abortMultipartUpload` |
+
+使用 STS 临时凭证时，按 ali-oss 文档配置 `refreshSTSToken` 即可，适配器无需感知。
+
+## 接入其他对象存储
+
+实现 `StorageDriver` 的四个必需方法即可获得全部服务能力；`deleteMany`、`copy` 缺失时服务层会自动降级，`list`、`signUrl`、`multipart` 缺失时抛出 `UNSUPPORTED`。
+
+```ts
+import { defineDriver, ObjectStorage, StorageError } from '@lhy-meta-server/meta-oss'
+
+const driver = defineDriver({
+  name: 'my-oss',
+  async put(key, payload, options) {
+    await sdk.upload(key, payload.stream(), { contentType: options.contentType, signal: options.signal })
+    return this.head(key, options)
+  },
+  async get(key, options) {
+    const response = await sdk.download(key, { signal: options.signal })
+    return { info: toInfo(key, response), body: response.body }
+  },
+  async head(key) {
+    return toInfo(key, await sdk.stat(key))
+  },
+  async delete(key) {
+    await sdk.remove(key)
+  },
+})
+
+const storage = new ObjectStorage({ driver })
+```
+
+适配器约定：
+
+- 收到的对象键已校验并包含服务级 `prefix`。
+- “对象不存在”应抛出 `NOT_FOUND`；SDK 抛出的 HTTP 404/403/409/5xx 等错误会被服务层自动归一化。
+- `payload.replayable` 为 `false` 时内容只能读取一次，`payload.size` 可能为 `undefined`。
+- `overwrite` 为 `false` 时应原子拒绝并抛出 `ALREADY_EXISTS`。
+- 尽量把 `signal` 传给底层 I/O，以便及时释放资源。
+
+## API
+
+### `new ObjectStorage(options)`
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `driver` | `StorageDriver` | 必填 | 存储适配器 |
+| `prefix` | `string` | `''` | 自动添加到所有键前的目录前缀，对业务透明 |
+| `timeout` | `number` | `30000` | 单次尝试超时毫秒数，`0` 表示不限制 |
+| `retry.retries` | `number` | `2` | 最大重试次数（0–10） |
+| `retry.baseDelay` | `number` | `100` | 首次重试等待毫秒数 |
+| `retry.maxDelay` | `number` | `2000` | 单次等待上限 |
+| `retry.jitter` | `boolean` | `true` | 是否叠加随机抖动 |
+| `retry.shouldRetry` | `(error, attempt) => boolean` | 仅 `retryable` 错误 | 自定义重试判定 |
+| `concurrency` | `number` | `32` | 对后端的最大在途请求数；超时/取消的请求在真正结束前仍占用额度 |
+| `abortGrace` | `number` | `5000` | 超时或取消后等待底层操作结束的最长毫秒数，超过后放弃追踪并释放额度 |
+| `multipartThreshold` | `number` | 64 MiB | 已知大小超过该值且适配器支持分片时，`put` 自动改用流式分片上传；`0` 禁用 |
+| `upload` | `UploadPolicy` | `{}` | 上传限制，见下文 |
+| `overwrite` | `boolean` | `true` | 同名对象默认是否覆盖 |
+| `contentTypes` | `Record<string, string>` | `{}` | 自定义扩展名 → MIME 映射 |
+| `partSize` | `number` | 8 MiB | 自动分片大小，不小于 100 KiB |
+| `partConcurrency` | `number` | `4` | 自动分片并行数 |
+| `observer` | `StorageObserver` | — | 结构化事件观察器 |
+| `metrics` | `StorageMetrics` | 私有实例 | 指标收集器，可跨实例共享 |
+
+所有方法都接受 `signal`、`timeout`、`retries` 以覆盖单次调用的默认值。
+
+| 方法 | 说明 |
+| --- | --- |
+| `put(key, body, options?)` | 写入对象，支持 `contentType`、`cacheControl`、`contentDisposition`、`metadata`、`overwrite` |
+| `get(key, { range? })` | 流式读取，返回 `{ info, body, range? }` |
+| `getBytes(key)` / `getText(key)` | 读取为字节或 UTF-8 文本 |
+| `head(key)` / `exists(key)` | 读取描述信息 / 判断是否存在 |
+| `delete(key)` | 删除对象，不存在时静默成功 |
+| `deleteMany(keys)` | 批量删除，返回 `{ deleted, failed }` |
+| `list({ prefix, delimiter, cursor, limit })` | 分页列举，返回 `{ objects, prefixes, cursor? }` |
+| `listAll({ prefix })` | 自动分页的异步迭代器 |
+| `copy(src, dst)` / `move(src, dst)` | 复制 / 移动，保留 HTTP 属性与元数据 |
+| `signUrl(key, { method, expiresIn, contentType, responseContentDisposition })` | 生成 `GET`/`PUT` 签名 URL |
+| `verifyUrl({ url, method, contentType })` | 校验本服务签发的签名 URL（自签名后端） |
+| `uploadMultipart(key, body, { partSize, concurrency })` | 流式自动分片上传，失败时自动中止 |
+| `createMultipart` / `uploadPart` / `completeMultipart` / `abortMultipart` | 手动分片，适用于断点续传 |
+| `getMetrics()` / `resetMetrics()` | 读取 / 重置指标 |
+| `close()` | 幂等关闭，之后的操作抛出 `CLOSED` |
+
+### 工具函数
+
+- `createObjectKey(filename, { directory?, date? })`：生成 `目录/yyyy/mm/dd/<uuid>.<ext>` 形式的不可预测键，原始文件名只用于提取扩展名。
+- `lookupContentType(key, overrides?)`：按扩展名推断 MIME。
+- `assertKey(key)`：按服务规则校验对象键。
+
+### 重试语义
+
+只有幂等或内容可重复读取的操作才会重试：字符串、二进制与 `Blob` 写入可重试，流式写入、`move`、`createMultipart`、`completeMultipart` 只尝试一次。调用方取消后不再重试。
+
+### 超时与取消语义
+
+- 超时或取消时调用方立即得到 `TIMEOUT` / `ABORTED`，同时把信号传给适配器以中断底层 I/O。
+- 并发额度与下一次重试都会等到底层操作真正结束（最长 `abortGrace`），因此超时不会导致后台请求堆积，重试也不会与残留写入并发操作同一对象。
+- 适配器因取消而抛出的次生错误（如连接中断）会统一报告为 `TIMEOUT` / `ABORTED`。
+- `get` 的超时只作用于打开对象；返回的流由调用方消费，可通过 `body.cancel()` 提前释放连接或文件句柄。
+
+## 上传策略与安全
+
+```ts
+new ObjectStorage({
+  driver,
+  upload: {
+    maxSize: 20 * 1024 * 1024,
+    allowedContentTypes: ['image/*', 'application/pdf'],
+    allowedExtensions: ['png', 'jpg', 'jpeg', 'webp', 'pdf'],
+    deniedExtensions: ['exe', 'sh', 'html', 'svg'],
+  },
+})
+```
+
+- 策略作用于 `put`、分片上传与 `PUT` 签名 URL；流式内容在读取过程中检查大小，超限即中止。
+- `PUT` 签名 URL 无法在服务端限制客户端上传的字节数，请结合网关或回调校验。
+- 对象键允许中文等 Unicode 字符，最长 1023 字节；拒绝空段、`.`、`..`、前导 `/`、盘符、反斜杠与控制字符。
+- 元数据键仅允许小写字母、数字与连字符，总大小不超过 8 KiB；HTTP 属性拒绝控制字符，防止头部注入。
+- 凭据只能通过构造参数传入，本包不读取任何环境变量。
+
+## 错误处理
+
+所有错误都是 `StorageError`，通过稳定的 `code` 判断：
+
+| `code` | 含义 | 默认可重试 |
+| --- | --- | --- |
+| `INVALID_KEY` | 对象键非法 | 否 |
+| `INVALID_OPTION` | 参数非法 | 否 |
+| `NOT_FOUND` | 对象或分片会话不存在 | 否 |
+| `ALREADY_EXISTS` | 禁止覆盖时目标已存在 | 否 |
+| `UPLOAD_REJECTED` | 违反上传策略 | 否 |
+| `UNSUPPORTED` | 适配器不支持该能力 | 否 |
+| `TIMEOUT` | 单次尝试超时 | 是 |
+| `ABORTED` | 调用方取消 | 否 |
+| `ACCESS_DENIED` | 权限不足或签名校验失败 | 否 |
+| `CLOSED` | 服务已关闭 | 否 |
+| `BACKEND` | 后端错误；408/429/5xx 与网络瞬时错误可重试 | 视情况 |
+
+```ts
+import { isStorageError } from '@lhy-meta-server/meta-oss'
+
+try {
+  return await storage.getText(key)
+} catch (error) {
+  if (isStorageError(error, 'NOT_FOUND')) return null
+  throw error
+}
+```
+
+错误对象还包含 `operation`、`key`、`retryable`，原始异常保存在 `cause` 中。
+
+## 可观测性
+
+```ts
+import { ObjectStorage, StorageMetrics } from '@lhy-meta-server/meta-oss'
+
+const metrics = new StorageMetrics()
+const storage = new ObjectStorage({
+  driver,
+  metrics,
+  observer: {
+    onOperation(event) {
+      logger.info(event, 'oss operation')
+      histogram.observe({ operation: event.operation, outcome: event.outcome }, event.duration)
+    },
+    onRetry(event) {
+      logger.warn({ operation: event.operation, attempt: event.attempt, delay: event.delay }, 'oss retry')
+    },
+  },
+})
+
+metrics.snapshot()
+// { operations, errors, retries, inFlight, bytesWritten, totalDuration, byOperation, byErrorCode }
+```
+
+`StorageEvent` 字段：`operation`、`outcome`、`driver`、`key`（不含前缀）、`duration`、`attempts`、`bytes`、`errorCode`、`error`、`timestamp`。观察器抛出的异常会被隔离，不影响业务请求。
+
+事件中的 `error` 是脱敏摘要 `StorageErrorSummary`（`code`、`message`、`retryable`、`status`、`causeCode`、`requestId`），可直接写入日志：不包含原始 SDK 错误对象，`BACKEND` 错误的消息也替换为固定文本，避免请求参数、请求头或签名随日志泄露。需要完整错误时请在业务调用处捕获 `StorageError` 并读取 `cause`。
+
+## 测试
+
+```bash
+bun run test           # 单元测试
+bun run test:coverage  # 覆盖率，函数与行均要求 100%
+bun run check          # 类型检查 + Lint + 覆盖率 + 构建 + Node/Bun 发布包运行验证
+```
+
+测试完全离线：本地存储使用临时目录，阿里云适配器使用模拟客户端，不需要真实凭据。
+
+## License
+
+[MIT](./LICENSE)

package/dist/ali-oss/client.d.ts

@@ -0,0 +1,185 @@
+import type { Readable } from 'node:stream';
+/**
+ * ali-oss 响应中的 HTTP 信息。
+ */
+export interface AliOssResponseInfo {
+    /**
+     * HTTP 状态码。
+     */
+    status?: number;
+    /**
+     * 响应头，键为小写。
+     */
+    headers?: Record<string, unknown>;
+}
+/**
+ * ali-oss 列举结果中的单个对象。
+ */
+export interface AliOssListObject {
+    /**
+     * 完整对象键。
+     */
+    name: string;
+    /**
+     * 对象字节数。
+     */
+    size: number;
+    /**
+     * 带引号的 ETag。
+     */
+    etag?: string;
+    /**
+     * ISO 格式的最后修改时间。
+     */
+    lastModified?: string;
+    /**
+     * 对象类型。
+     */
+    type?: string;
+}
+/**
+ * ali-oss `list` 方法的返回值。
+ */
+export interface AliOssListResult {
+    /**
+     * 对象列表；没有对象时可能为 `undefined`。
+     */
+    objects?: AliOssListObject[];
+    /**
+     * 公共前缀；没有时可能为 `null`。
+     */
+    prefixes?: string[] | null;
+    /**
+     * 是否还有下一页。
+     */
+    isTruncated?: boolean;
+    /**
+     * 下一页的 marker。
+     */
+    nextMarker?: string | null;
+}
+/**
+ * 适配器调用 ali-oss 时使用的请求选项子集。
+ */
+export interface AliOssRequestOptions {
+    /**
+     * MIME 类型。
+     */
+    mime?: string;
+    /**
+     * 自定义元数据，SDK 会转换为 `x-oss-meta-*` 头部。
+     */
+    meta?: Record<string, string>;
+    /**
+     * 额外请求头。
+     */
+    headers?: Record<string, string>;
+    /**
+     * 请求超时毫秒数。
+     */
+    timeout?: number;
+    /**
+     * 是否以安静模式批量删除。
+     */
+    quiet?: boolean;
+}
+/**
+ * 适配器依赖的 ali-oss 客户端最小结构。
+ *
+ * 本包不依赖 `ali-oss`：业务自行安装并创建 `new OSS({...})` 实例后直接传入，
+ * 适配器只调用以下稳定方法，因此同样兼容 `OSS.Cluster` 或自定义封装。
+ */
+export interface AliOssClient {
+    /**
+     * 上传 Buffer。
+     */
+    put(name: string, file: Buffer, options?: AliOssRequestOptions): Promise<{
+        res: AliOssResponseInfo;
+    }>;
+    /**
+     * 上传 Node.js 可读流。
+     */
+    putStream(name: string, stream: Readable, options?: AliOssRequestOptions & {
+        contentLength?: number;
+    }): Promise<{
+        res: AliOssResponseInfo;
+    }>;
+    /**
+     * 以流方式下载。
+     */
+    getStream(name: string, options?: AliOssRequestOptions): Promise<{
+        stream: Readable;
+        res: AliOssResponseInfo;
+    }>;
+    /**
+     * 读取对象头部。
+     */
+    head(name: string, options?: AliOssRequestOptions): Promise<{
+        res: AliOssResponseInfo;
+        status?: number;
+    }>;
+    /**
+     * 读取对象元信息（不受 gzip 影响的准确大小与 ETag）；可选，新版 SDK 提供。
+     */
+    getObjectMeta?(name: string, options?: AliOssRequestOptions): Promise<{
+        res: AliOssResponseInfo;
+        status?: number;
+    }>;
+    /**
+     * 删除对象。
+     */
+    delete(name: string, options?: AliOssRequestOptions): Promise<unknown>;
+    /**
+     * 批量删除对象。
+     */
+    deleteMulti(names: string[], options?: AliOssRequestOptions): Promise<{
+        deleted?: Array<string | {
+            Key: string;
+        }>;
+    }>;
+    /**
+     * 列举对象。
+     */
+    list(query: {
+        prefix?: string;
+        delimiter?: string;
+        marker?: string;
+        'max-keys'?: number;
+    }, options?: AliOssRequestOptions): Promise<AliOssListResult>;
+    /**
+     * 服务端复制对象。
+     */
+    copy(name: string, sourceName: string, options?: AliOssRequestOptions): Promise<unknown>;
+    /**
+     * 同步生成签名 URL（旧版 SDK）。
+     */
+    signatureUrl?(name: string, options?: Record<string, unknown>): string;
+    /**
+     * 异步生成签名 URL（新版 SDK，支持 STS 自动刷新）。
+     */
+    asyncSignatureUrl?(name: string, options?: Record<string, unknown>): Promise<string>;
+    /**
+     * 初始化分片上传。
+     */
+    initMultipartUpload(name: string, options?: AliOssRequestOptions): Promise<{
+        uploadId: string;
+    }>;
+    /**
+     * 上传分片，`start` 与 `end` 为 `file` 中的字节偏移（`end` 不包含在内）。
+     */
+    uploadPart(name: string, uploadId: string, partNumber: number, file: Buffer, start: number, end: number, options?: AliOssRequestOptions): Promise<{
+        etag: string;
+    }>;
+    /**
+     * 完成分片上传。
+     */
+    completeMultipartUpload(name: string, uploadId: string, parts: Array<{
+        number: number;
+        etag: string;
+    }>, options?: AliOssRequestOptions): Promise<unknown>;
+    /**
+     * 放弃分片上传。
+     */
+    abortMultipartUpload(name: string, uploadId: string, options?: AliOssRequestOptions): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/ali-oss/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ali-oss/client.ts"],"names":[],"mappings":"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"}