@heybox/hb-sdk 0.7.5-alpha.0 → 0.8.0-alpha.10

package/types/core/client.d.ts

@@ -25,8 +25,18 @@ export interface MiniProgramRequester {
     /** 向父容器调用指定开放能力。 */
     request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
 }
+/** 长操作使用的本地 observer 与取消配置，不进入 bridge payload。 */
+export interface MiniProgramOperationOptions<TProgress = unknown> {
+    signal?: AbortSignal;
+    onProgress?: (progress: TProgress) => void;
+    createAbortError?: () => unknown;
+}
+/** 支持 request-scoped progress/cancel 的 bridge requester。 */
+export interface MiniProgramOperationRequester extends MiniProgramRequester {
+    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
+}
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
-export declare class MiniProgramBridgeClient implements MiniProgramRequester {
+export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
@@ -64,6 +74,9 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
     /** 调用父容器开放能力。 */
     request<Method extends MiniProgramBridgeMethod>(method: Method, ...args: MiniProgramRequesterArgs<Method>): Promise<MiniProgramCapabilityResult<Method>>;
+    /** 发起不使用固定总时长 timer 的长操作。 */
+    requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
+    private performRequest;
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy(): void;
     private ensureStarted;
@@ -73,6 +86,9 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private postCSPViolation;
     private handleEvent;
     private handleResponse;
+    private handleOperationProgress;
+    private sendCancel;
+    private cleanupPending;
     private postMessage;
     private resolveHandshakeOnce;
     private failHandshake;

package/types/core/errors.d.ts

@@ -18,9 +18,9 @@ export declare class HbMiniProgramSDKError extends Error {
 /**
  * 创建 SDK 标准错误。
  *
- * @param code 稳定错误码。
- * @param message 面向开发者的错误说明。
- * @param data 可选调试数据。
+ * @param code - 稳定错误码。
+ * @param message - 面向开发者的错误说明。
+ * @param data - 可选调试数据。
  * @returns 标准化 `HbMiniProgramSDKError` 实例。
  *
  * @remarks
@@ -34,7 +34,7 @@ export declare function createSDKError(code: string, message: string, data?: unk
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
  * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
  *
- * @typeParam T 标准化响应数据的类型。
+ * @typeParam T - 标准化响应数据的类型。
  */
 export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** HTTP 状态码。 */
@@ -48,7 +48,7 @@ export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
     /** 完整标准化响应。 */
     response: MiniProgramNetworkResponse<T>;
     /**
-     * @param response 已完成请求的标准化网络响应。
+     * @param response - 已完成请求的标准化网络响应。
      */
     constructor(response: MiniProgramNetworkResponse<T>);
 }

package/types/core/sdk.d.ts

@@ -4,6 +4,7 @@ import { type MiniProgramCloudModule } from '../modules/cloud';
 import { type MiniProgramShareModule } from '../modules/share';
 import { type MiniProgramStorageModule } from '../modules/storage';
 import { type MiniProgramNetworkModule } from '../modules/network';
+import { type FilesModule } from '../modules/files';
 import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
 import { type MiniProgramUiModule } from '../modules/ui';
@@ -37,6 +38,8 @@ export declare class MiniProgramSDK {
     readonly storage: MiniProgramStorageModule;
     /** 网络请求相关开放能力。 */
     readonly network: MiniProgramNetworkModule;
+    /** 受控文件与目录能力。 */
+    readonly files: FilesModule;
     /** UI 交互相关开放能力。 */
     readonly ui: MiniProgramUiModule;
     /** 设备相关开放能力。 */
@@ -53,16 +56,16 @@ export declare class MiniProgramSDK {
     /**
      * 注册小程序生命周期或业务事件。
      *
-     * @param eventName 要监听的事件名。
-     * @param handler 事件处理函数。
+     * @param eventName - 要监听的事件名。
+     * @param handler - 事件处理函数。
      * @returns 事件解绑函数。
      */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /**
      * 移除小程序生命周期或业务事件。
      *
-     * @param eventName 要移除的事件名。
-     * @param handler 对应的事件处理函数。
+     * @param eventName - 要移除的事件名。
+     * @param handler - 对应的事件处理函数。
      */
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
     /**
@@ -77,7 +80,7 @@ export declare class MiniProgramSDK {
 /**
  * 创建独立 SDK 实例。
  *
- * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
  * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
  *
  * @remarks

package/types/core/singleton.d.ts

@@ -3,6 +3,7 @@ import type { MiniProgramCloudModule } from '../modules/cloud';
 import type { MiniProgramShareModule } from '../modules/share';
 import type { MiniProgramStorageModule } from '../modules/storage';
 import type { MiniProgramNetworkModule } from '../modules/network';
+import type { FilesModule } from '../modules/files';
 import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
 import type { MiniProgramUiModule } from '../modules/ui';
@@ -10,24 +11,74 @@ import type { MiniProgramDeviceModule } from '../modules/device';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
-/** 获取默认 SDK 实例的当前握手状态。 */
+/**
+ * 获取默认 SDK 实例的当前握手状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function getHandshakeState(): MiniProgramSDKHandshakeState;
-/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+/**
+ * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName 要监听的事件名。
- * @param handler 事件处理函数。
+ * @param eventName - 要监听的事件名。
+ * @param handler - 事件处理函数。
  * @returns 事件解绑函数。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName 要移除的事件名。
- * @param handler 对应的事件处理函数。
+ * @param eventName - 要移除的事件名。
+ * @param handler - 对应的事件处理函数。
  * @returns 无返回值。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
 /** 默认 SDK 实例的授权模块。 */
@@ -42,6 +93,8 @@ export declare const viewport: MiniProgramViewportModule;
 export declare const storage: MiniProgramStorageModule;
 /** 默认 SDK 实例的 network 模块。 */
 export declare const network: MiniProgramNetworkModule;
+/** 默认 SDK 实例的 files 模块。 */
+export declare const files: FilesModule;
 /** 默认 SDK 实例的 UI 模块。 */
 export declare const ui: MiniProgramUiModule;
 /** 默认 SDK 实例的 device 模块。 */

package/types/index.d.ts

@@ -1,5 +1,5 @@
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud, } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, navigation, cloud, } from './core/singleton';
 export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
@@ -10,7 +10,8 @@ export type { UserInfoAuthorizationScope } from './modules/user';
 export type { CopyLinkPayload, CopyLinkResult, MiniProgramCopyLinkOptions, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
 export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
 export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload } from './modules/storage';
-export type { MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
+export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
+export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, MiniProgramUiModule, ShowLoadingPayload, ShowLoadingResult, ShowToastPayload, ShowToastResult, } from './modules/ui';
 export type { MiniProgramDeviceModule, MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult, } from './modules/device';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
@@ -25,6 +26,7 @@ declare const hbSDK: {
     share: import(".").MiniProgramShareModule;
     viewport: import(".").MiniProgramViewportModule;
     storage: import(".").MiniProgramStorageModule;
+    files: import(".").FilesModule;
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;

package/types/miniapp-manifest/index.d.ts

@@ -1,2 +1,3 @@
 export * from './schema';
 export * from './node';
+export * from './permissions';

package/types/miniapp-manifest/node.d.ts

@@ -1 +1,4 @@
+import { type ParsedMiniappPermissions } from './permissions';
 export declare function readMiniappVersionFromPackageJson(root: string): string;
+export declare function readMiniappPermissionsFromPackageJson(root: string, sdkVersion: string): ParsedMiniappPermissions;
+export declare function resolveMiniappSdkVersion(): string;

package/types/miniapp-manifest/permissions.d.ts

@@ -0,0 +1,37 @@
+import { type MiniProgramPermissionKey, type MiniProgramRuntimePermissionsSnapshot } from '@heybox/hb-sdk-protocol';
+export declare const MINIAPP_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network"];
+export type MiniappPermissionKey = MiniProgramPermissionKey;
+export interface SimpleMiniappPermissionDeclaration {
+    enabled: true;
+}
+export interface NetworkMiniappPermissionDeclaration extends SimpleMiniappPermissionDeclaration {
+    useOfficialDomain: boolean;
+}
+export type MiniappPermissionDeclarations = Partial<Record<Exclude<MiniappPermissionKey, 'network'>, SimpleMiniappPermissionDeclaration> & {
+    network: NetworkMiniappPermissionDeclaration;
+}>;
+export interface ParsedMiniappPermissions {
+    declared: boolean;
+    permissions?: MiniappPermissionDeclarations;
+}
+export interface MiniappPermissionView {
+    key: MiniappPermissionKey;
+    access: 'declaration' | 'platform-approval';
+    declared: boolean;
+    approved: boolean | null;
+    requestedConfig?: Record<string, boolean>;
+    approvedConfig?: Record<string, boolean>;
+    effective: boolean;
+    effectiveConfig?: Record<string, boolean>;
+}
+export declare function parseMiniappPermissions(value: unknown, options: {
+    present: boolean;
+    sdkVersion: string;
+    sourceLabel?: string;
+}): ParsedMiniappPermissions;
+export declare function requiresExplicitPermissions(sdkVersion: string): boolean;
+export declare function getMissingPermissionsWarning(sourceLabel?: string): string;
+export declare function composeMiniappRuntimePermissions(local: ParsedMiniappPermissions, approvals: unknown): {
+    runtimePermissions: MiniProgramRuntimePermissionsSnapshot;
+    views: MiniappPermissionView[];
+};

package/types/miniapp-manifest/schema.d.ts

@@ -1,8 +1,13 @@
+import { type MiniappPermissionDeclarations } from './permissions';
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
+export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
+export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
 export interface MiniappManifest {
     [key: string]: unknown;
     sdkVersion: string;
     version: string;
+    platforms: readonly MiniappPlatform[];
+    permissions?: MiniappPermissionDeclarations;
 }
 export interface ParseMiniappManifestResult {
     manifest: MiniappManifest;
@@ -14,7 +19,12 @@ export declare function validateMiniappManifestVersion(version: unknown, sourceL
 export declare function renderMiniappManifest(manifest: MiniappManifest): string;
 export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
+    permissions?: Partial<Record<"storage" | "userInfo" | "steamLibrary" | "share" | "filesystem" | "clipboard" | "leaderboard", import("./permissions").SimpleMiniappPermissionDeclaration> & {
+        network: import("./permissions").NetworkMiniappPermissionDeclaration;
+    }> | undefined;
     version: string;
     sdkVersion: string;
+    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
 };
+export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
 export declare function validateSdkVersion(version: unknown, sourceLabel?: string): string;

package/types/miniapp-publish/index.d.ts

@@ -71,7 +71,7 @@ export interface MiniappUploadSessionFile {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -81,8 +81,8 @@ export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFil
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
@@ -92,7 +92,7 @@ export declare function validateMiniappUploadPathLengths(files: readonly Pick<Mi
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -100,7 +100,7 @@ export declare function createMiniappArtifactSignatureHeader(fileCount: number):
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -108,9 +108,9 @@ export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFil
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */

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

@@ -16,7 +16,21 @@ export interface LoginResult {
 export type { MiniProgramAuthMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的授权模块。 */
 export interface MiniProgramAuthModule {
-    /** 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。 */
+    /**
+     * 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。
+     *
+     * @since 0.2.0-alpha.0
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     login(options?: LoginOptions): Promise<LoginResult>;
 }
 /** 获取短期授权码。 */

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

@@ -81,15 +81,85 @@ export interface GetLeaderboardInfoResult {
 }
 /** 外部小程序可调用的云端排行榜模块。 */
 export interface MiniProgramCloudLeaderboardModule {
-    /** 提交当前用户分数。 */
+    /**
+     * 提交当前用户分数。
+     *
+     * @since 0.5.11
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     submit(options: SubmitLeaderboardEntryPayload): Promise<SubmitLeaderboardEntryResult>;
-    /** 读取排行榜列表。 */
+    /**
+     * 读取排行榜列表。
+     *
+     * @since 0.5.11
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     getList(options?: GetLeaderboardListPayload): Promise<GetLeaderboardListResult>;
-    /** 读取当前用户记录。 */
+    /**
+     * 读取当前用户记录。
+     *
+     * @since 0.5.11
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     getCurrentUserEntry(options?: GetCurrentUserLeaderboardEntryPayload): Promise<GetCurrentUserLeaderboardEntryResult>;
-    /** 删除当前用户记录。 */
+    /**
+     * 删除当前用户记录。
+     *
+     * @since 0.5.11
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     deleteCurrentUserEntry(options?: DeleteCurrentUserLeaderboardEntryPayload): Promise<DeleteCurrentUserLeaderboardEntryResult>;
-    /** 读取排行榜基础信息。 */
+    /**
+     * 读取排行榜基础信息。
+     *
+     * @since 0.5.11
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     getInfo(options?: GetLeaderboardInfoPayload): Promise<GetLeaderboardInfoResult>;
 }
 /** 外部小程序可调用的云端能力模块。 */

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

@@ -1,5 +1,5 @@
 import type { MiniProgramRequester } from '../../core/client';
-export { DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, } from '../../protocol/capabilities';
+export { DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD } from '../../protocol/capabilities';
 /** 震动强度。 */
 export type MiniProgramVibrateIntensity = 'light' | 'medium' | 'heavy';
 /** `device.vibrate` 入参。 */
@@ -21,9 +21,37 @@ export type SetClipboardResult = void;
 export type { MiniProgramDeviceMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 device 模块。 */
 export interface MiniProgramDeviceModule {
-    /** 触发宿主震动反馈。 */
+    /**
+     * 触发宿主震动反馈。
+     *
+     * @since 0.4.4
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     vibrate(options?: VibratePayload): Promise<void>;
-    /** 写入系统文本剪贴板。 */
+    /**
+     * 写入系统文本剪贴板。
+     *
+     * @since 0.4.4
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android none
+     * @hbClient ios none
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     setClipboard(options: SetClipboardPayload): Promise<void>;
 }
 /** 触发宿主震动反馈。 */

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

@@ -0,0 +1,5 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { FilesModule } from './types';
+export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './types';
+/** 创建当前 SDK session 的 files 模块。 */
+export declare function createFilesModule(requester: MiniProgramRequester): FilesModule;

package/types/modules/files/registry.d.ts

@@ -0,0 +1,35 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramDirectoryDescriptor, MiniProgramDirectoryRef, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileRef, MiniProgramFileSystemEntityDescriptor } from '@heybox/hb-sdk-protocol';
+import type { DirectoryHandle, FileHandle, FileSystem, FileSystemEntity } from './types';
+interface FileHandleState {
+    ref: MiniProgramFileRef;
+    mode: MiniProgramFileMode;
+}
+interface DirectoryHandleState {
+    ref: MiniProgramDirectoryRef;
+    mode: MiniProgramFileMode;
+}
+/** 校验并返回平台无关的 `/` 分隔逻辑相对路径。 */
+export declare function normalizeRelativePath(value: unknown): string;
+export declare class MiniProgramFileHandleRegistry {
+    private readonly requester;
+    private readonly fileStates;
+    private readonly directoryStates;
+    private readonly pathRootStates;
+    private sandboxRoot?;
+    constructor(requester: MiniProgramRequester);
+    getSandbox(): FileSystem;
+    createFile(descriptor: MiniProgramFileDescriptor): FileHandle;
+    createDirectFile(descriptor: MiniProgramFileDescriptor): FileHandle;
+    createDirectory(descriptor: MiniProgramDirectoryDescriptor): DirectoryHandle;
+    createDirectDirectory(descriptor: MiniProgramDirectoryDescriptor): DirectoryHandle;
+    createEntity(descriptor: MiniProgramFileSystemEntityDescriptor): FileSystemEntity;
+    requireFile(handle: unknown): FileHandleState;
+    requireDirectory(handle: unknown): DirectoryHandleState;
+    private definePathRootMethods;
+    private assertFileDescriptor;
+    private assertDirectoryDescriptor;
+}
+export declare function getFileHandleRegistry(requester: MiniProgramRequester): MiniProgramFileHandleRegistry;
+export declare function isMiniProgramFileSystemValue(value: unknown): value is FileSystem | FileSystemEntity;
+export {};