@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/modules/network/index.d.ts

@@ -3,11 +3,24 @@ import type { DirectoryHandle, FileHandle } from '../files';
 export { NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
 export { createNetworkRequestFailureLog, formatNetworkRequestFailureMessage, logNetworkRequestFailure, previewNetworkData, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from './observability';
 export { describeHostNetworkFailure, isMultipartContentType, isUnsupportedMultipartNetworkRequest, looksLikeMultipartBody, NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE, readNetworkContentType, } from './request-shape';
-/** `network.request` 请求头。 */
+/**
+ * `network.request` 请求头。
+ *
+ * @remarks
+ * 键必须是无首尾空白的合法 HTTP header name，值必须是无换行/控制字符的字符串。
+ * `Host`、`Content-Length`、hop-by-hop/framing Header 以及平台保留的认证 Header 会以
+ * `INVALID_PARAMS` 拒绝。响应侧不会向小程序暴露 `Set-Cookie`、认证凭据或平台保留 Header。
+ */
 export type MiniProgramNetworkHeaders = Record<string, string>;
-/** `network.request` 查询参数。 */
+/**
+ * `network.request` 查询参数，由 Host 编码到请求 URL。
+ *
+ * @remarks
+ * 必须是普通对象。为获得跨 Host 一致的查询字符串，优先使用 string/number/boolean 等标量值；
+ * `null`、`undefined`、数组和嵌套对象的具体 URL 编码不属于公共稳定契约。
+ */
 export type MiniProgramNetworkParams = Record<string, unknown>;
-/** `network.request` 支持的 HTTP 方法。 */
+/** `network.request` 支持的 HTTP 方法；省略时使用 `GET`。 */
 export type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 /**
  * SDK 侧可配置的状态校验函数。
@@ -16,54 +29,149 @@ export type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' |
  * @returns 返回 `true` 时表示本次响应应视为成功。
  *
  * @remarks
- * 该函数只在 SDK 侧执行，不会跨 bridge 传输到父容器 runtime。
+ * 该函数只在 SDK 收到并标准化响应后执行，不会跨 bridge 传输到 Host。默认仅接受 `200`
+ * 至 `299`；可返回 `true` 接受 3xx/4xx 等完成态响应。函数自身抛出的异常会原样向调用方传播，
+ * 不会包装成 SDK 或 Network 错误。
  */
 export type MiniProgramNetworkValidateStatus = (status: number) => boolean;
 /**
  * 对外开放的网络请求配置。
  *
  * @remarks
- * 该配置面向业务层，保持 axios-like 的窄接口，不暴露宿主协议的原始字段。
+ * 该配置面向业务层，保持 axios-like 的窄接口，不暴露宿主协议的原始字段。请求进入 bridge
+ * 时会复制 plain object/array 数据并移除 `validateStatus`；响应中的 `config` 由 SDK 另行构造。
  */
 export interface MiniProgramNetworkRequestConfig {
-    /** 请求地址。 */
+    /**
+     * 绝对请求地址。必须是无 username/password 的 HTTP(S) URL；生产环境只允许 HTTPS，本地
+     * 开发仅允许 Host 明确放行的数字 loopback/LAN HTTP origin。官方域名要求
+     * `package.json#heybox.permissions.network.useOfficialDomain` 的声明值与平台批准值都为
+     * `true`；Runtime auth、OpenAPI 内部路径和官方账号敏感路径始终禁止访问。
+     */
     url: string;
-    /** HTTP 方法，默认 `GET`。 */
+    /** HTTP 方法，默认 `GET`；仅支持 {@link MiniProgramNetworkRequestMethod} 中列出的值。 */
     method?: MiniProgramNetworkRequestMethod;
-    /** 查询参数，会被编码到请求 URL。 */
+    /** 查询参数；必须是普通对象，SDK 会递归复制 plain object/array 后交给 Host 编码。 */
     params?: MiniProgramNetworkParams;
-    /** 请求体。 */
+    /**
+     * 请求体。
+     *
+     * @remarks
+     * 支持可序列化的 JSON-compatible 值与原始字符串，总大小不得超过 2 MiB。plain object/array
+     * 会递归复制，因此复用同一子对象可以，但循环引用会以 `INVALID_PARAMS` 拒绝。`GET`/`HEAD`
+     * 不应携带 body。
+     *
+     * 第三方 URL 的非字符串 JSON-compatible 值默认按 JSON 发送；官方域名为兼容既有 Host，
+     * plain object/array 在未显式设置 Content-Type 时默认按 form 编码。要强制 JSON，请设置
+     * `Content-Type: application/json`；表单请传
+     * `new URLSearchParams(values).toString()` 并设置
+     * `application/x-www-form-urlencoded`。
+     *
+     * 不支持 `FormData`、`Blob`、File/Directory 代理、`ArrayBuffer`、TypedArray、`DataView`、
+     * `SharedArrayBuffer` 或它们的嵌套值。`multipart/form-data` 与手写 multipart body 均不可用；
+     * 文件传输应使用专用能力。
+     */
     data?: unknown;
-    /** 请求头。 */
+    /**
+     * 请求头；规则见 {@link MiniProgramNetworkHeaders}。调用方显式提供的普通 `Cookie` /
+     * `Authorization` 可作为应用 Header 交给 Host，但 SDK 不提供平台 Cookie/token，且不得在
+     * 小程序中持有或发送平台凭据、服务端应用密钥等敏感信息。
+     */
     headers?: MiniProgramNetworkHeaders;
-    /** 超时时间，单位毫秒。 */
+    /**
+     * Host 请求超时，单位毫秒；必须是 `0` 至 `30000` 的有限数字。省略或 `0` 时的具体默认
+     * 行为由 Host 决定；业务需要明确超时时应传正数。
+     */
     timeout?: number;
-    /** SDK 侧状态校验；不会跨 bridge 传输函数值。 */
+    /** SDK 侧状态校验；默认只接受 2xx，函数本身不会跨 bridge，详见 {@link MiniProgramNetworkValidateStatus}。 */
     validateStatus?: MiniProgramNetworkValidateStatus;
 }
-/** 流式下载的 request-scoped 进度。 */
+/**
+ * 流式下载的 request-scoped 进度。
+ *
+ * @remarks
+ * Runtime 会过滤倒退、负数、超出可信 `Content-Length` 或 `maxBytes` 的进度，并在原子提交后、
+ * `download()` resolve 前发送一次最终进度。最终值可能与上一次相同，空文件也会发送
+ * `loaded: 0`；不要依赖回调次数或严格递增。
+ */
 export interface DownloadProgress {
+    /** 已接收并写入临时目标的非负字节数；原子提交完成前不表示原目标已改变。 */
     loaded: number;
+    /** 可从可信响应 framing 确定总长度时的非负字节数；未知、分块或压缩响应时省略。 */
     total?: number;
+    /** `total` 是否存在且可用于计算百分比；为 `false` 时应展示不定进度。 */
     lengthComputable: boolean;
 }
+/**
+ * 流式下载两种 target 分支共享的地址、限制、取消与进度选项。
+ *
+ * @remarks
+ * 下载固定使用 GET、拒绝重定向，不接受 `method`、`data`、`body`、Range/If-Range/A-IM
+ * 等部分响应字段。响应字节由 Host 直接写入临时目标，不经过 iframe bridge。
+ */
 export interface DownloadBaseOptions {
+    /**
+     * 下载地址。必须是无 username/password 的 HTTP(S) URL；生产环境只允许 HTTPS，本地开发
+     * 仅允许 Host 明确放行的 loopback/LAN HTTP origin。当前公开 Host 的流式下载 adapter 不支持
+     * 小黑盒官方域名，即使 `network.useOfficialDomain` 已声明并获批也不应依赖；Runtime/账号
+     * 敏感路径始终禁止访问。
+     */
     url: string;
+    /** 查询参数；必须是对象，SDK 会复制后交给 Host 编码到下载 URL。 */
     params?: MiniProgramNetworkParams;
+    /**
+     * 请求头；必须是合法的字符串字典。Host/framing/hop-by-hop、平台保留认证头以及
+     * `Range`、`If-Range`、`A-IM` 会以 `INVALID_PARAMS` 拒绝。普通 `Authorization` / `Cookie`
+     * 不会被 Runtime 一律拒绝，但移动端下载不会自动附带 Host credential；鉴权资源优先使用
+     * 短期签名 URL。
+     */
     headers?: MiniProgramNetworkHeaders;
+    /** 网络与响应 body 的空闲超时，单位毫秒；必须是有限正数，不是整个下载的总时长。 */
     timeout?: number;
+    /**
+     * 单次下载可提交的最大字节数；必须是正的 safe integer。可信 `Content-Length` 已超限时
+     * 会在写入前返回 `FILE_TOO_LARGE`，流式传输过程中超限也不会提交部分文件。
+     */
     maxBytes?: number;
+    /**
+     * 用于取消当前下载。调用前已 aborted 会立即返回 `DOWNLOAD_CANCELLED`；提交前取消获胜时
+     * 原目标保持不变，Host 已完成原子提交时则成功结果优先。
+     */
     signal?: AbortSignal;
+    /**
+     * 接收当前下载的标准化 {@link DownloadProgress}。回调本身不会序列化到 bridge；回调抛错
+     * 不会中断下载。`lengthComputable` 为 `false` 时不要按 `total` 计算百分比。
+     */
     onProgress?: (progress: DownloadProgress) => void;
 }
-/** File target 原子替换，Directory target 创建或替换子文件。 */
+/**
+ * 下载目标选项。
+ *
+ * @remarks
+ * File target 必须是当前 SDK session 中已存在的 `readwrite` {@link FileHandle}。下载成功后
+ * 原子替换该文件并返回传入的同一个代理，不接受 `suggestedName` 或 `overwrite`。
+ *
+ * Directory target 必须是当前 SDK session 中已存在的 `readwrite` {@link DirectoryHandle}。
+ * 下载会在其中创建一个直接子文件并返回新的冻结 `readwrite` File 代理；默认独占创建，
+ * 同名目标返回 `FILE_ALREADY_EXISTS`，仅 `overwrite: true` 允许原子创建或替换。
+ */
 export type DownloadOptions = DownloadBaseOptions & ({
+    /** 当前 SDK session 创建的 `readwrite` File 代理；目标文件必须已存在。成功后返回同一代理。 */
     to: FileHandle;
+    /** File target 不接受该字段；即使显式传入字符串也返回 `INVALID_PARAMS`。 */
     suggestedName?: never;
+    /** File target 固定原子替换，不接受该字段；即使显式传入 boolean 也返回 `INVALID_PARAMS`。 */
     overwrite?: never;
 } | {
+    /** 当前 SDK session 创建的、已存在的 `readwrite` Directory 代理；成功后返回其直接子 File 代理。 */
     to: DirectoryHandle;
+    /**
+     * 建议的安全子文件 basename。服务端安全 `Content-Disposition filename*` / `filename`
+     * 优先于该值；之后依次回退 URL basename 与 `download.bin`。不能包含路径分隔符、点段、
+     * 控制字符、Windows 保留名或尾随点/空格，最长 255 个 Unicode 字符。
+     */
     suggestedName?: string;
+    /** 是否允许原子创建或替换目录内的同名文件，默认 `false`；`false` 时采用独占创建。 */
     overwrite?: boolean;
 });
 /**
@@ -73,44 +181,124 @@ export type DownloadOptions = DownloadBaseOptions & ({
  * 这是从公开配置中裁剪得到的可序列化请求载荷，不包含函数值或内部实现细节。
  */
 export interface NetworkRequestPayload {
+    /** 请求地址。 */
     url: string;
+    /** HTTP 方法；省略时由 Host 按 `GET` 处理。 */
     method?: MiniProgramNetworkRequestMethod;
+    /** 查询参数。 */
     params?: MiniProgramNetworkParams;
+    /** 可序列化请求体。 */
     data?: unknown;
+    /** 字符串请求头。 */
     headers?: MiniProgramNetworkHeaders;
+    /** 请求超时时间，单位毫秒。 */
     timeout?: number;
 }
 /**
  * bridge / runtime 返回的标准化 HTTP 响应。
  *
- * @typeParam T - 标准化响应数据的类型。
+ * @typeParam T - 调用方声明的响应数据类型；只影响 TypeScript，不执行运行时 schema 校验。
  */
 export interface NetworkResponsePayload<T = unknown> {
+    /** Host 标准化后的响应数据；泛型 `T` 只提供 TypeScript 类型，不执行运行时 schema 校验。 */
     data: T;
+    /** 已完成 HTTP 响应的状态码。 */
     status: number;
+    /** 可用时的 HTTP 状态文本。 */
     statusText?: string;
+    /**
+     * Host 返回的安全字符串响应头；无有效响应头时为空对象。`Set-Cookie`、认证凭据以及
+     * `x-heybox-*` / `x-xhh-*` 平台保留 Header 会在跨 bridge 前移除。
+     */
     headers: MiniProgramNetworkHeaders;
 }
 /**
  * SDK 对外暴露的网络响应。
  *
- * @typeParam T - 标准化响应数据的类型。
+ * @typeParam T - 调用方期望的响应数据类型；SDK 不会在运行时校验 Host 返回值是否符合该类型。
+ *
+ * @remarks
+ * `config` 不包含 Host 内部 route、body encoding、Cookie 状态或协议字段。bridge 请求在调用时
+ * 使用独立克隆；响应完成时，SDK 再从原始公开 config 构造响应快照，递归复制其中的 plain
+ * object/array，并保留同一个 `validateStatus` 函数引用。因此请求进行期间对原 config 的修改
+ * 不会改变已发送 payload，但可能反映在完成时生成的 `response.config` 中。
  */
 export interface MiniProgramNetworkResponse<T = unknown> extends NetworkResponsePayload<T> {
-    /** 发起请求时的 SDK 公共配置快照。 */
+    /** 响应标准化时构造的 SDK 公共配置快照；对象和数组已复制，`validateStatus` 保留原函数引用。 */
     config: MiniProgramNetworkRequestConfig;
 }
 export type { MiniProgramNetworkMethod } from '../../protocol/capabilities';
-/** 外部小程序可调用的网络模块。 */
+/**
+ * Mini-program 可调用的受控网络模块。
+ *
+ * @remarks
+ * `request()` 与 `download()` 都要求声明并获得 `network` 平台批准，并使用 no-follow redirect policy。
+ * `download()` 还要求 `filesystem`，且响应字节由 Host 直接写入受控目标，不经过 iframe bridge。
+ */
 export interface MiniProgramNetworkModule {
     /**
      * 发起网络请求。
      *
-     * @param config - 面向业务层的网络请求配置。
-     * @returns 标准化网络响应；HTTP 2xx 默认返回 resolve。
-     * @throws 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出 `HbMiniProgramNetworkError`。
-     * @throws 当 bridge、运行时或宿主能力调用失败时抛出 `HbMiniProgramSDKError`。
-     * @remarks 自 0.8.1-alpha.7 起不再支持 `withCredentials` 配置：传入会被忽略且不报错，请从代码中移除；原生 Cookie 由客户端按目标域名决定。该 method 本身仍受支持，V1 没有替代调用入口。
+     * @typeParam T - 调用方期望的响应 data 类型；只影响 TypeScript，不做运行时 schema 校验。
+     * @param config - URL、方法、查询、body、Header、Host timeout 与 SDK 状态校验配置，详见
+     * {@link MiniProgramNetworkRequestConfig}。
+     * @returns 通过 `validateStatus` 的标准化 {@link MiniProgramNetworkResponse}；默认仅 2xx
+     * resolve。响应包含安全 Header 与公开 config 快照。
+     * @throws {@link HbMiniProgramNetworkError} Host 已完成 HTTP 响应，但状态未通过
+     * `validateStatus` 时抛出；错误的 `status`、`data`、安全 `headers`、`config` 与 `response`
+     * 可用于业务分支。它不表示权限、bridge 或网络不可达。
+     * @throws {@link HbMiniProgramSDKError} 配置/数据/Header 非法时返回 `INVALID_PARAMS`；未声明、
+     * 未批准 `network` 或未获官方域名批准时返回 `PERMISSION_NOT_DECLARED` /
+     * `PERMISSION_DENIED`；Host 不支持请求形态时返回 `REQUEST_UNSUPPORTED`，Host/transport
+     * 失败返回 `REQUEST_FAILED`，Host 能力关闭或旧 Runtime 不认识 method 时可返回
+     * `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`，响应结构无效返回 `INVALID_NETWORK_RESPONSE`；
+     * 其他握手、bridge 或 Host 错误保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 该 API 需要在 `package.json#heybox.permissions` 声明并启用 `network`，且取得平台批准；
+     * 不需要 `filesystem` 或可信用户手势。`useOfficialDomain` 只有开发者声明与平台批准都为
+     * `true` 时生效，并且不会绕过 HTTPS、敏感路径、Header、body、timeout 或响应策略。
+     *
+     * 公开请求使用 no-follow redirect policy。3xx 不会自动访问 `Location`；它作为已完成响应
+     * 返回到 SDK，默认触发 {@link HbMiniProgramNetworkError}，只有自定义 `validateStatus`
+     * 接受时才 resolve。平台保留的 Runtime auth/OpenAPI 路径始终不能通过该能力访问。
+     *
+     * 自 0.8.1-alpha.7 起公开 config 不再支持 `withCredentials`；JavaScript 仍传入时会被 SDK
+     * 忽略且不报错，也不会把凭据开关传给 Host。原生 Cookie 是否随请求发送由 Host 按目标
+     * 域名决定，iframe Cookie 不会由 SDK 自动读取；响应中的 `Set-Cookie` 与认证 Header 不会
+     * 暴露给页面。应用显式 Header 仍必须遵守敏感信息边界。
+     *
+     * Browser Dev Host 与真实 App Host 都拒绝 multipart，并执行相同的 no-follow、官方域名和
+     * 敏感路径策略；本地代理另有 5 MiB 响应体上限，真机 Host 仍可能有不同的响应限制。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * type ItemsResult = { items: string[] } | { message: string }
+     *
+     * const response = await hbSDK.network.request<ItemsResult>({
+     *   url: 'https://api.example.com/items',
+     *   method: 'POST',
+     *   params: { page: 1, locale: 'zh-CN' },
+     *   data: { filters: ['owned'] },
+     *   headers: { 'content-type': 'application/json', 'x-request-id': 'request-1' },
+     *   timeout: 10_000,
+     *   validateStatus: (status) => (status >= 200 && status < 300) || status === 404,
+     * })
+     *
+     * if (response.status === 404) console.log('暂无数据')
+     * else if ('items' in response.data) console.log(response.data.items)
+     * ```
+     *
+     * @see {@link MiniProgramNetworkRequestConfig}
+     * @see {@link MiniProgramNetworkResponse}
+     * @see {@link HbMiniProgramNetworkError}
+     * @see {@link HbMiniProgramSDKError}
+     * @see {@link MiniProgramNetworkModule.download | network.download}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
      * @hbPlatform ios
@@ -127,8 +315,84 @@ export interface MiniProgramNetworkModule {
     /**
      * 将 GET 响应流式写入受控 File/Directory target。
      *
-     * @param options - 下载地址、写入目标、取消信号与进度回调。
-     * @returns 原子提交完成后的目标文件代理。
+     * @param options - 下载地址、File/Directory 写入目标、限制、取消信号与进度回调；两种 target
+     * 分支及全部字段见 {@link DownloadOptions}。
+     * @returns Host 完成原子提交后的 `readwrite` {@link FileHandle}。File target 返回传入的同一
+     * 代理；Directory target 返回目标目录中新建或替换的直接子 File 代理。
+     * @throws {@link HbMiniProgramSDKError} 参数、URL、Header、目标或 Host 返回值不合法时返回
+     * `INVALID_PARAMS` / `INVALID_NETWORK_RESPONSE`；未声明或未启用 `network`、`filesystem`
+     * 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 能力缺失时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 非成功或部分 HTTP 响应返回 `DOWNLOAD_HTTP_STATUS`；
+     * 网络/响应 framing 失败、空闲超时、提交前取消或超出 `maxBytes` 分别返回
+     * `DOWNLOAD_NETWORK_FAILED`、`DOWNLOAD_TIMEOUT`、`DOWNLOAD_CANCELLED`、`FILE_TOO_LARGE`。
+     * 文件授权、存在性、同名冲突、类型、配额和 I/O 失败返回对应稳定 `FILE_*` /
+     * `DIRECTORY_*` 错误码。下载不会抛出 {@link HbMiniProgramNetworkError}。
+     *
+     * @remarks
+     * 需要同时声明并启用 `network` 与 `filesystem`，其中 `network` 还必须获得平台批准；访问
+     * 当前公开 Host 的流式下载 adapter 不支持小黑盒官方域名；`useOfficialDomain` 的批准不能
+     * 单独保证 `download()` 可用，也不会绕过敏感路径、Header、重定向、大小或超时策略。
+     * 下载本身不要求可信用户手势，但外部 File/Directory
+     * 必须事先通过 files picker 或 `saveFile()` 获得当前 session 的 `readwrite` 授权。
+     *
+     * 固定使用 GET，不跟随重定向，也不接受 body、Range、上传或自定义 `validateStatus`。
+     * 非 2xx、206、226 与 `Content-Range` 都不会进入文件提交；`DOWNLOAD_HTTP_STATUS.data`
+     * 仅包含脱敏的 status、可选 statusText 和安全响应头。响应字节留在 Host，并直接流式写入
+     * 临时目标，不经过 iframe bridge。
+     *
+     * `timeout` 是网络/响应 body 空闲超时；`maxBytes` 是单次提交上限。Host 只有在长度与大小
+     * 约束全部满足并完成原子提交后才会 resolve。取消、超时、超限或其他失败不会改动原目标；
+     * signal 与原子提交竞态时，提交前取消返回 `DOWNLOAD_CANCELLED`，提交已完成则仍返回成功。
+     *
+     * Directory 文件名按安全的 `Content-Disposition filename*`、`filename`、`suggestedName`、
+     * URL basename、`download.bin` 依次选择；不安全的响应候选会跳过，但调用方显式提供的非法
+     * `suggestedName` 会在 Host I/O 前返回 `INVALID_PARAMS`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const directory = hbSDK.files.sandbox.directory('downloads')
+     * await directory.create({ recursive: true })
+     *
+     * const controller = new AbortController()
+     * const file = await hbSDK.network.download({
+     *   url: 'https://cdn.example.com/report.json',
+     *   to: directory,
+     *   params: { format: 'full' },
+     *   headers: { accept: 'application/json' },
+     *   suggestedName: 'report.json',
+     *   overwrite: true,
+     *   timeout: 15_000,
+     *   maxBytes: 8 * 1024 * 1024,
+     *   signal: controller.signal,
+     *   onProgress: ({ loaded, total, lengthComputable }) => {
+     *     console.log(lengthComputable ? `${loaded}/${total}` : loaded)
+     *   },
+     * })
+     *
+     * const exactFile = hbSDK.files.sandbox.file('downloads/latest.json')
+     * await exactFile.create()
+     * const replaced = await hbSDK.network.download({
+     *   url: 'https://cdn.example.com/latest.json',
+     *   to: exactFile,
+     * })
+     * console.log(replaced === exactFile) // true
+     * ```
+     *
+     * @see {@link DownloadOptions}
+     * @see {@link DownloadProgress}
+     * @see {@link FileSystem.file | files.sandbox.file}
+     * @see {@link FileSystem.directory | files.sandbox.directory}
+     * @see {@link FilesModule.pickFiles | files.pickFiles}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link FilesModule.saveFile | files.saveFile}
+     * @see {@link MiniProgramNetworkModule.request | network.request}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
@@ -165,7 +429,14 @@ export interface MiniProgramNetworkModule {
  * ```
  */
 export declare function request<T = unknown>(requester: MiniProgramRequester, config: MiniProgramNetworkRequestConfig): Promise<MiniProgramNetworkResponse<T>>;
-/** 发起不使用 bridge 固定总时长 timer 的流式下载。 */
+/**
+ * 发起不使用 bridge 固定总时长 timer 的流式下载。
+ *
+ * @param requester - 支持 request-scoped 取消与进度的 bridge 请求能力。
+ * @param options - 下载地址、受控写入目标、限制、取消信号与进度回调。
+ * @returns 原子提交完成后的 File 代理。
+ * @throws {@link HbMiniProgramSDKError} 参数、权限、目标、网络、取消或 Host 响应不符合公开合同时抛出。
+ */
 export declare function download(requester: MiniProgramOperationRequester, options: DownloadOptions): Promise<FileHandle>;
 /**
  * 创建 network 模块。

package/types/modules/share/copy-link.d.ts

@@ -1,16 +1,46 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramCopyLinkOptions } from './types';
 export { SHARE_COPY_LINK_METHOD } from '../../protocol/capabilities';
-/** `share.copyLink` 入参。 */
+/** `share.copyLink` 入参；省略后生成不带 `extra` 的通用分享链接。 */
 export type CopyLinkPayload = MiniProgramCopyLinkOptions | undefined;
-/** `share.copyLink` 返回已复制的完整分享链接。 */
+/**
+ * `share.copyLink` 返回值；内容与 Host 已写入系统剪贴板的完整分享链接一致。
+ *
+ * @remarks Promise 只在剪贴板写入成功后 resolve；写入失败时调用直接 reject，不返回链接。
+ */
 export type CopyLinkResult = string;
 /**
  * 复制当前小程序的通用分享链接。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 分享扩展数据；不传时复制默认首页链接。
- * @returns 已写入系统剪贴板的完整分享链接。
- * @throws {@link HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
+ * @param options - 可选配置；只接受本次链接需要携带的 `extra`。省略 `options` 或
+ * `options.extra` 时生成不带扩展数据的链接。
+ * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
+ * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
+ * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
+ * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+ * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
+ * 对应错误码。
+ *
+ * @remarks 该方法生成当前小程序的固定通用落地页，不复制当前页面路径或 hash，也不继承
+ * 启动 URL 中已有的 `extra`。显式传入的 `extra` 会先编码，再作为 Base64URL 参数写入链接；
+ * 接收方使用 {@link MiniProgramShareModule.getExtra | share.getExtra} 读取还原值。
+ *
+ * 该调用需要声明 `share` 权限，但不额外要求 `clipboard` 权限或可信用户手势。它只写入
+ * 系统剪贴板，不会打开分享面板或自动显示成功提示。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const copiedUrl = await hbSDK.share.copyLink({
+ *   extra: { page: 'ranking', season: 12 },
+ * })
+ *
+ * console.log('已复制分享链接', copiedUrl)
+ * ```
+ *
+ * @see {@link MiniProgramShareModule.getExtra | share.getExtra}
+ * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
  */
 export declare function copyLink(requester: MiniProgramRequester, options?: MiniProgramCopyLinkOptions): Promise<CopyLinkResult>;