@lark-apaas/dataloom 0.1.1-alpha.1 → 0.1.1-alpha.2

package/README.md

@@ -1,3 +1,814 @@
 # @lark-apaas/dataloom
 
-Dataloom client SDK for @lark-apaas (storage + service). Migrated from @data-loom/js.
+面向 `@lark-apaas` 的浏览器端 Dataloom SDK，当前聚焦于 `service` 与 `storage`
+两部分能力。该包由原 `@data-loom/js` 相关能力迁移并精简而来，仅保留当前客户端实际需要的功能。
+
+## 功能概览
+
+当前 SDK 提供以下能力：
+
+- `service.user`：用户检索与批量查询
+- `service.session`：登录跳转、登出、当前用户信息、个人中心跳转
+- `storage`：基于 `bucketId` 的文件上传、下载、移动、复制、删除、签名链接等能力
+
+当前版本仅支持浏览器环境，不提供 Node.js 兼容垫片。
+
+## 运行环境
+
+使用前请确认运行环境满足以下条件：
+
+- 浏览器环境
+- 可用的 `fetch` / `Headers` / `Request` / `Response`
+- 页面中可访问 `window.location`
+- 页面中可访问 `document.cookie`
+
+## 安装
+
+```bash
+pnpm add @lark-apaas/dataloom
+```
+
+## 导出内容
+
+包根入口当前导出：
+
+- `DataloomClient`
+- `createClient`
+- `DataloomClientOptions`
+
+示例：
+
+```ts
+import { createClient } from '@lark-apaas/dataloom';
+```
+
+## 快速开始
+
+```ts
+import { createClient } from '@lark-apaas/dataloom';
+
+const client = createClient(
+  'https://example.com',
+  'dataloom-key',
+  {
+    global: {
+      brandName: 'miaoda',
+      appId: 'app_xxx',
+    },
+  },
+);
+```
+
+创建完成后，可以通过以下入口访问能力：
+
+- `client.service.user`
+- `client.service.session`
+- `client.storage.from(bucketId)`
+
+## 初始化
+
+### `createClient(...)`
+
+```ts
+createClient(
+  dataloomUrl: string,
+  dataloomKey: string,
+  options?: DataloomClientOptions,
+)
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `dataloomUrl` | `string` | 是 | Dataloom 服务地址 |
+| `dataloomKey` | `string` | 是 | 访问 Dataloom 的 key |
+| `options` | `DataloomClientOptions` | 否 | 初始化配置 |
+
+#### 返回
+
+| 返回值 | 类型 | 说明 |
+| --- | --- | --- |
+| 返回结果 | `DataloomClient` | SDK 客户端实例 |
+
+### `DataloomClientOptions`
+
+当前支持的 `global` 配置如下：
+
+```ts
+type DataloomClientOptions = {
+  global?: {
+    brandName: string;
+    appId: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    enableDataloomLog?: boolean;
+    requestRateLimit?: number;
+    onError?: (error: any, instance: any) => void;
+  };
+};
+```
+
+#### `global` 配置项
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `brandName` | `string` | 是 | 品牌标识，供 session / profile 逻辑使用 |
+| `appId` | `string` | 是 | 业务 appId，供 service / storage 请求使用 |
+| `fetch` | `typeof fetch` | 否 | 自定义 fetch 实现 |
+| `headers` | `Record<string, string>` | 否 | 额外请求头 |
+| `enableDataloomLog` | `boolean` | 否 | 是否开启请求日志 |
+| `requestRateLimit` | `number` | 否 | 5 秒窗口内最大请求数 |
+| `onError` | `(error, instance) => void` | 否 | 请求失败时的全局钩子 |
+
+完整示例：
+
+```ts
+const client = createClient(
+  'https://example.com',
+  'dataloom-key',
+  {
+    global: {
+      brandName: 'miaoda',
+      appId: 'app_xxx',
+      headers: {
+        'x-custom-header': 'demo',
+      },
+      enableDataloomLog: false,
+      requestRateLimit: 5,
+      onError(error, instance) {
+        console.error('[dataloom error]', error, instance);
+      },
+    },
+  },
+);
+```
+
+## Service API
+
+## `client.service.user`
+
+用户相关 API。
+
+### `search(params)`
+
+按关键字搜索用户。
+
+```ts
+const result = await client.service.user.search({
+  name: 'Alice',
+  pageSize: 10,
+});
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `params.name` | `string` | 是 | 搜索关键字 |
+| `params.pageSize` | `number` | 否 | 返回数量 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data.user_list` | `User[]` | 用户列表 |
+| `data.user_list[].user_id` | `string` | 用户 ID |
+| `data.user_list[].email` | `string` | 邮箱 |
+| `data.user_list[].name` | `string` | 展示名称 |
+| `data.user_list[].avatar` | `string` | 头像地址 |
+| `data.user_list[].status` | `UserStatus` | 用户状态 |
+| `error` | `ErrorShape \| null` | 错误信息 |
+| `status` | `number` | HTTP 状态码 |
+| `statusText` | `string` | HTTP 状态文本 |
+
+### `getByIds(ids)`
+
+按用户 ID 批量获取用户信息。
+
+```ts
+const result = await client.service.user.getByIds([1, 2, 3]);
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ids` | `string[] \| number[]` | 是 | 用户 ID 列表 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data.user_list` | `User[]` | 用户列表，顺序与入参 `ids` 一致 |
+| `data.user_list[].user_id` | `string` | 用户 ID；未命中时为空字符串 |
+| `data.user_list[].email` | `string` | 邮箱；未命中时为空字符串 |
+| `data.user_list[].name` | `string` | 用户名称；未命中时为空字符串 |
+| `data.user_list[].avatar` | `string` | 头像地址；未命中时为空字符串 |
+| `data.user_list[].status` | `UserStatus` | 用户状态 |
+| `error` | `ErrorShape \| null` | 错误信息 |
+| `status` | `number` | HTTP 状态码 |
+| `statusText` | `string` | HTTP 状态文本 |
+
+## `client.service.session`
+
+会话相关 API，仅支持浏览器环境。
+
+### `redirectToLogin(options?)`
+
+跳转到登录页。
+
+```ts
+client.service.session.redirectToLogin();
+
+client.service.session.redirectToLogin({
+  newTab: true,
+  returnUrl: 'https://example.com/callback',
+});
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options.returnUrl` | `string` | 否 | 登录完成后的回跳地址，默认使用当前页面地址 |
+| `options.newTab` | `boolean` | 否 | 是否在新标签页打开，默认 `false` |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `'success' \| null` | 成功时返回 `'success'` |
+| `error` | `ErrorShape \| null` | 非浏览器环境下返回错误 |
+| `status` | `number` | 状态码 |
+| `statusText` | `string` | 状态文本 |
+
+#### 说明
+
+- 若当前页面路径以 `/spark` 开头，会生成 `/spark/faas/...` 登录地址
+- 否则生成 `/app/...` 登录地址
+
+### `signOut()`
+
+退出当前登录态。
+
+```ts
+await client.service.session.signOut();
+```
+
+#### 入参
+
+无。
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `null` | 成功时通常为空 |
+| `error` | `ErrorShape \| null` | 错误信息 |
+| `status` | `number` | 状态码 |
+| `statusText` | `string` | 状态文本 |
+
+### `getUrlWithBizSource()`
+
+获取带 `biz_source` 参数的当前页面 URL。
+
+```ts
+const currentUrl = client.service.session.getUrlWithBizSource();
+```
+
+#### 入参
+
+无。
+
+#### 返回
+
+| 返回值 | 类型 | 说明 |
+| --- | --- | --- |
+| 返回结果 | `string` | 带 `biz_source` 的当前页面 URL；非浏览器环境返回空字符串 |
+
+### `getUserInfo()`
+
+获取当前登录用户信息。
+
+```ts
+const result = await client.service.session.getUserInfo();
+```
+
+#### 入参
+
+无。
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data.user_info` | `UserBaseInfo` | 当前用户信息 |
+| `data.user_info.user_id` | `number \| undefined` | 用户 ID |
+| `data.user_info.name` | `I18ns \| undefined` | 多语言名称 |
+| `data.user_info.avatar` | `Avatar \| undefined` | 头像信息 |
+| `data.user_info.email` | `string \| undefined` | 邮箱 |
+| `data.user_info.phone_number` | `string \| undefined` | 脱敏手机号 |
+| `error` | `ErrorShape \| null` | 错误信息 |
+| `status` | `number` | 状态码 |
+| `statusText` | `string` | 状态文本 |
+
+### `navigateToUserProfile(options?)`
+
+跳转到用户个人中心页。
+
+```ts
+client.service.session.navigateToUserProfile();
+
+client.service.session.navigateToUserProfile({ newTab: true });
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options.newTab` | `boolean` | 否 | 是否在新标签页打开，默认 `false` |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `'success' \| null` | 成功时返回 `'success'` |
+| `error` | `ErrorShape \| null` | 非浏览器环境下返回错误 |
+| `status` | `number` | 状态码 |
+| `statusText` | `string` | 状态文本 |
+
+## Storage API
+
+Storage 能力以 bucket 为作用域，需要先通过 `from(bucketId)` 获取文件操作实例。
+
+```ts
+const storage = client.storage.from('assets');
+```
+
+## `client.storage.from(bucketId)`
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `bucketId` | `string` | 是 | 目标 bucket 标识 |
+
+#### 返回
+
+| 返回值 | 类型 | 说明 |
+| --- | --- | --- |
+| 返回结果 | `StorageFileApi` | bucket 级文件操作实例 |
+
+### `upload(path, fileBody, fileOptions?)`
+
+上传文件。
+
+```ts
+const file = new File(['hello'], 'hello.txt', { type: 'text/plain' });
+
+await client.storage.from('assets').upload('docs/hello.txt', file, {
+  contentType: 'text/plain',
+  upsert: true,
+});
+```
+
+也支持以下重载形式：
+
+```ts
+await client.storage.from('assets').upload(file, {
+  filePath: 'docs/hello.txt',
+  contentType: 'text/plain',
+});
+```
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | 条件必填 | 目标文件路径，使用重载 1 时必填 |
+| `fileBody` | `FileBody` | 是 | 文件内容，支持 `Blob`、`File`、`ArrayBuffer`、`FormData`、`string` 等 |
+| `fileOptions.cacheControl` | `string \| number` | 否 | 浏览器/CDN 缓存时间 |
+| `fileOptions.contentType` | `string` | 否 | 文件内容类型 |
+| `fileOptions.upsert` | `boolean` | 否 | 是否允许覆盖 |
+| `fileOptions.duplex` | `string` | 否 | 流式上传配置 |
+| `fileOptions.metadata` | `Record<string, any>` | 否 | 附加元数据 |
+| `fileOptions.headers` | `Record<string, string>` | 否 | 附加请求头 |
+| `fileOptions.filePath` | `string` | 条件必填 | 使用重载 2 时的目标路径 |
+| `fileOptions.contentDisposition` | `string` | 否 | 下载时的文件名响应头 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data.id` | `string` | 文件 ID |
+| `data.file_path` | `string` | 文件路径 |
+| `data.bucket_id` | `string` | bucket ID |
+| `data.download_url` | `string` | 下载地址 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `uploadFile(fileBody, fileOptions?)`
+
+与 `upload(fileBody, { filePath })` 类似。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `fileBody` | `FileBody` | 是 | 文件内容 |
+| `fileOptions.filePath` | `string` | 否 | 上传目标路径 |
+| `fileOptions.cacheControl` | `string \| number` | 否 | 缓存时间 |
+| `fileOptions.contentType` | `string` | 否 | 内容类型 |
+| `fileOptions.upsert` | `boolean` | 否 | 是否允许覆盖 |
+| `fileOptions.contentDisposition` | `string` | 否 | 下载响应头文件名 |
+
+#### 返回
+
+与 `upload` 相同。
+
+### `update(path, fileBody, fileOptions?)`
+
+更新已存在的文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | 是 | 文件路径 |
+| `fileBody` | `FileBody` | 是 | 文件内容 |
+| `fileOptions` | `FileOptions` | 否 | 更新配置 |
+
+#### 返回
+
+与 `upload` 相同。
+
+### `list(path?, options?)`
+
+列出目录下文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | 否 | 目录前缀 |
+| `options.limit` | `number` | 否 | 返回条数 |
+| `options.offset` | `number` | 否 | 偏移量 |
+| `options.sortBy` | `SortBy` | 否 | 排序配置 |
+| `options.search` | `string` | 否 | 搜索关键字 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `FileObject[]` | 文件列表 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `download(path)`
+
+下载文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | 是 | 文件路径 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `Blob \| null` | 下载结果 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `createSignedUrl(path, expiresIn)`
+
+创建单个文件的签名链接。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | 是 | 文件路径 |
+| `expiresIn` | `number` | 是 | 过期时间，单位秒 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data.signedUrl` | `string` | 签名链接 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `createSignedUrls(paths, expiresIn)`
+
+批量创建签名链接。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `paths` | `string[]` | 是 | 文件路径列表 |
+| `expiresIn` | `number` | 是 | 过期时间，单位秒 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `{ path: string \| null; signedUrl: string; error: string \| null }[]` | 签名链接列表 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `remove(paths)`
+
+删除文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `paths` | `string[]` | 是 | 文件路径列表 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `FileObject[]` | 删除结果 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `move(fromPath, toPath)`
+
+移动文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `fromPath` | `string` | 是 | 原路径 |
+| `toPath` | `string` | 是 | 目标路径 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `{ message: string } \| null` | 移动结果 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `copy(fromPath, toPath)`
+
+复制文件。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `fromPath` | `string` | 是 | 原路径 |
+| `toPath` | `string` | 是 | 目标路径 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `FileObjectV2 \| null` | 复制结果 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+### `copyFromUrl(url, path, options?)`
+
+将外部 URL 文件复制到 bucket 中。
+
+#### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 外部资源地址 |
+| `path` | `string` | 是 | 目标路径 |
+| `options.cacheControl` | `string \| number` | 否 | 缓存时间 |
+| `options.contentType` | `string` | 否 | 文件类型 |
+| `options.upsert` | `boolean` | 否 | 是否允许覆盖 |
+
+#### 返回
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | `UploadFileData \| null` | 复制结果 |
+| `error` | `StorageError \| null` | 错误信息 |
+
+## 错误处理
+
+大多数异步 API 都返回统一结构：
+
+```ts
+{
+  data: T | null;
+  error: ErrorShape | null;
+  status?: number;
+  statusText?: string;
+}
+```
+
+推荐使用方式：
+
+```ts
+const result = await client.service.user.search({ name: 'Alice' });
+
+if (result.error) {
+  console.error(result.error.message);
+  return;
+}
+
+console.log(result.data);
+```
+
+Storage 相关错误类型也可以从包根入口获取，例如：
+
+```ts
+import {
+  StorageApiError,
+  StorageError,
+  StorageUnknownError,
+} from '@lark-apaas/dataloom';
+```
+
+### Service 错误结构
+
+Service 异常响应中的 `error` 字段结构如下：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `code` | `number` | 错误码 |
+| `message` | `string` | 错误信息 |
+| `details` | `string` | 详细描述 |
+| `hint` | `string \| null` | 补充提示 |
+
+对应类型：
+
+```ts
+type DataloomServiceError = {
+  code: number;
+  details: string;
+  hint: string | null;
+  message: string;
+};
+```
+
+### Storage 错误类型
+
+Storage 使用异常对象表达错误，常见类型如下：
+
+| 类型 | 继承关系 | 说明 | 关键字段 |
+| --- | --- | --- | --- |
+| `StorageError` | `Error` | Storage 基础错误类型 | `message` |
+| `StorageApiError` | `StorageError` | 服务端 API 返回错误 | `message`、`status`、`statusCode` |
+| `StorageUnknownError` | `StorageError` | 未知错误或非预期异常包装 | `message`、`originalError` |
+
+## Slardar 上报说明
+
+`dataloom` 已接入 `@lark-apaas/internal-slardar`，用于在 SDK 内部关键错误节点发生异常时上报日志，便于排查线上问题。
+
+### 上报范围
+
+当前已覆盖的主要场景包括：
+
+- client 统一请求失败入口（`onRequestError`）
+- `service.session` 在非浏览器环境下的错误调用
+- `storage` 侧高层 unknown error catch 分支
+- `storage/libs/fetch.ts` 中的底层请求失败
+- `storage/libs/fetch.ts` 中的响应 JSON 解析失败
+
+### 上报字段
+
+Slardar 上报时会附带一组分类字段，当前常见字段如下：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `source` | `string` | 固定为 `dataloom` |
+| `module` | `string` | 出错模块，例如 `client`、`session-service`、`storage-file-api`、`storage-fetch` |
+| `method` | `string` | 出错方法名，部分场景存在 |
+| `phase` | `string` | 出错阶段，例如 `request`、`response-json-parse`、`blob` |
+| `type` | `string` | 错误类别，例如 `runtime`、`unknown` |
+| `appId` | `string` | 当前 appId，部分场景存在 |
+
+### 降级保证
+
+Slardar 上报逻辑不会影响 `dataloom` 本身行为：
+
+- `@lark-apaas/internal-slardar` 自身已做容错
+- `dataloom` 内部的 `reportDataloomException(...)` 也额外包裹了 `try/catch`
+
+因此即使 Slardar SDK 未加载、调用失败、或上报逻辑本身抛错，也不会中断正常业务流程。
+
+## 核心类型附录
+
+以下是 README 中高频出现的核心返回结构，便于不翻源码时快速理解字段。
+
+### `User`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `user_id` | `string` | 用户 ID |
+| `email` | `string` | 邮箱 |
+| `name` | `string` | 用户名称 |
+| `avatar` | `string` | 头像地址 |
+| `status` | `UserStatus` | 用户状态 |
+
+### `UserBaseInfo`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `user_id` | `number \| undefined` | 用户 ID |
+| `name` | `I18ns \| undefined` | 多语言名称 |
+| `avatar` | `Avatar \| undefined` | 头像信息 |
+| `email` | `string \| undefined` | 邮箱 |
+| `phone_number` | `string \| undefined` | 脱敏手机号 |
+| `tenant_name` | `string \| undefined` | 租户名称 |
+
+### `Avatar`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `source` | `string \| undefined` | 头像来源 |
+| `image.large` | `string \| undefined` | 大图地址 |
+| `color` | `string \| undefined` | 头像主题色 |
+
+### `I18n` / `I18ns`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `language_code` | `number` | 语言编码 |
+| `text` | `string` | 文本内容 |
+
+说明：
+
+- `I18n` 表示单条多语言内容
+- `I18ns` 表示 `I18n[]`
+
+### `UploadFileData`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string` | 文件 ID |
+| `file_path` | `string` | 文件路径 |
+| `bucket_id` | `string` | bucket ID |
+| `download_url` | `string` | 下载地址 |
+
+### `FileObject`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string` | 文件 ID |
+| `name` | `string` | 文件名称 |
+| `bucket_id` | `string` | bucket ID |
+| `owner` | `string` | 所有者 |
+| `created_at` | `string` | 创建时间 |
+| `updated_at` | `string` | 更新时间 |
+| `created_by` | `string` | 创建人 |
+| `updated_by` | `string` | 更新人 |
+| `last_accessed_at` | `string \| undefined` | 最后访问时间 |
+| `metadata` | `Record<string, any>` | 元数据 |
+| `buckets` | `Bucket` | 所属 bucket 信息 |
+
+### `FileObjectV2`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string` | 文件 ID |
+| `version` | `string` | 版本号 |
+| `name` | `string` | 文件名称 |
+| `bucket_id` | `string` | bucket ID |
+| `created_at` | `string` | 创建时间 |
+| `updated_at` | `string` | 更新时间 |
+| `last_accessed_at` | `string` | 最后访问时间 |
+| `size` | `number \| undefined` | 文件大小 |
+| `cache_control` | `string \| undefined` | 缓存控制 |
+| `content_type` | `string \| undefined` | 内容类型 |
+| `etag` | `string \| undefined` | ETag |
+| `last_modified` | `string \| undefined` | 最后修改时间 |
+| `metadata` | `Record<string, any> \| undefined` | 元数据 |
+
+### `Bucket`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string` | bucket ID |
+| `type` | `'STANDARD' \| 'ANALYTICS' \| undefined` | bucket 类型 |
+| `name` | `string` | bucket 名称 |
+| `owner` | `string` | 所有者 |
+| `file_size_limit` | `number \| undefined` | 文件大小限制 |
+| `allowed_mime_types` | `string[] \| undefined` | 允许的 MIME 类型 |
+| `created_at` | `string` | 创建时间 |
+| `updated_at` | `string` | 更新时间 |
+| `public` | `boolean` | 是否公开 |
+
+## 开发
+
+```bash
+pnpm build
+pnpm test
+pnpm lint
+pnpm check
+```
+
+## 测试
+
+- 测试框架：`vitest`
+- 运行环境：`jsdom`
+- 覆盖率范围：`src/**/*.ts`
+
+覆盖率已排除构建产物，报告会聚焦真实源码，而不是 `lib` 目录中的生成文件。