@heybox/hb-sdk 0.1.3 → 0.2.0-alpha.1

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

@@ -0,0 +1,120 @@
+import type { MiniProgramRequester } from '../../core/client';
+export { NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
+/** `network.request` 请求头。 */
+export type MiniProgramNetworkHeaders = Record<string, string>;
+/** `network.request` 查询参数。 */
+export type MiniProgramNetworkParams = Record<string, unknown>;
+/** `network.request` 支持的 HTTP 方法。 */
+export type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * SDK 侧可配置的状态校验函数。
+ *
+ * @param status 标准化后的 HTTP 状态码。
+ * @returns 返回 `true` 时表示本次响应应视为成功。
+ *
+ * @remarks
+ * 该函数只在 SDK 侧执行，不会跨 bridge 传输到父容器 runtime。
+ */
+export type MiniProgramNetworkValidateStatus = (status: number) => boolean;
+/**
+ * 对外开放的网络请求配置。
+ *
+ * @remarks
+ * 该配置面向业务层，保持 axios-like 的窄接口，不暴露 `sendRequestV2`
+ * 等宿主协议的原始字段。
+ */
+export interface MiniProgramNetworkRequestConfig {
+    /** 请求地址。 */
+    url: string;
+    /** HTTP 方法，默认 `GET`。 */
+    method?: MiniProgramNetworkRequestMethod;
+    /** 查询参数，会被编码到请求 URL。 */
+    params?: MiniProgramNetworkParams;
+    /** 请求体。 */
+    data?: unknown;
+    /** 请求头。 */
+    headers?: MiniProgramNetworkHeaders;
+    /** 超时时间，单位毫秒。 */
+    timeout?: number;
+    /** 是否携带凭据意图；具体策略由宿主运行时决定。 */
+    withCredentials?: boolean;
+    /** SDK 侧状态校验；不会跨 bridge 传输函数值。 */
+    validateStatus?: MiniProgramNetworkValidateStatus;
+}
+/**
+ * bridge / runtime 可消费的网络请求 payload。
+ *
+ * @remarks
+ * 这是从公开配置中裁剪得到的可序列化请求载荷，不包含函数值或内部实现细节。
+ */
+export interface NetworkRequestPayload {
+    url: string;
+    method?: MiniProgramNetworkRequestMethod;
+    params?: MiniProgramNetworkParams;
+    data?: unknown;
+    headers?: MiniProgramNetworkHeaders;
+    timeout?: number;
+    withCredentials?: boolean;
+}
+/**
+ * bridge / runtime 返回的标准化 HTTP 响应。
+ *
+ * @typeParam T 标准化响应数据的类型。
+ */
+export interface NetworkResponsePayload<T = unknown> {
+    data: T;
+    status: number;
+    statusText?: string;
+    headers: MiniProgramNetworkHeaders;
+}
+/**
+ * SDK 对外暴露的网络响应。
+ *
+ * @typeParam T 标准化响应数据的类型。
+ */
+export interface MiniProgramNetworkResponse<T = unknown> extends NetworkResponsePayload<T> {
+    /** 发起请求时的 SDK 公共配置快照。 */
+    config: MiniProgramNetworkRequestConfig;
+}
+export type { MiniProgramNetworkMethod } from '../../protocol/capabilities';
+/** 外部小程序可调用的网络模块。 */
+export interface MiniProgramNetworkModule {
+    /**
+     * 发起网络请求。
+     *
+     * @param config 面向业务层的网络请求配置。
+     * @returns 标准化网络响应；HTTP 2xx 默认返回 resolve。
+     * @throws {HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
+     * @throws {HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
+     */
+    request<T = unknown>(config: MiniProgramNetworkRequestConfig): Promise<MiniProgramNetworkResponse<T>>;
+}
+/**
+ * 发起网络请求并返回标准化响应。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param config 面向业务层的网络请求配置。
+ * @returns 标准化网络响应。HTTP 2xx 默认返回 resolve。
+ * @throws {HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
+ * @throws {HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
+ *
+ * @remarks
+ * `validateStatus` 仅在 SDK 侧执行，不会跨 bridge 传输函数值。
+ * 公开配置与返回结构都保持 axios-like 的窄接口，不暴露宿主原始协议字段。
+ *
+ * @example
+ * ```ts
+ * const result = await request(requester, {
+ *   url: 'https://api.xiaoheihe.cn/demo',
+ *   method: 'GET',
+ * })
+ * ```
+ */
+export declare function request<T = unknown>(requester: MiniProgramRequester, config: MiniProgramNetworkRequestConfig): Promise<MiniProgramNetworkResponse<T>>;
+/**
+ * 创建 network 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的网络模块对象。
+ */
+export declare function createNetworkModule(requester: MiniProgramRequester): MiniProgramNetworkModule;

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

@@ -1,12 +1,11 @@
 import type { MiniProgramRequester } from '../../core/client';
-import { SHARE_SCREENSHOT_METHOD, type ScreenshotResult } from './screenshot';
-import { SHARE_SHOW_SHARE_MENU_METHOD, type ShowShareMenuPayload, type ShowShareMenuResult } from './show-share-menu';
+import { type ScreenshotResult } from './screenshot';
+import { type ShowShareMenuPayload, type ShowShareMenuResult } from './show-share-menu';
 import type { MiniProgramScreenshotOptions } from './types';
 export * from './screenshot';
 export * from './show-share-menu';
 export * from './types';
-/** 分享模块开放的方法名。 */
-export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
+export type { MiniProgramShareMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的分享模块。 */
 export interface MiniProgramShareModule {
     /** 展示基础分享面板。 */
@@ -14,5 +13,10 @@ export interface MiniProgramShareModule {
     /** 截图并唤起分享。 */
     screenshot(options?: MiniProgramScreenshotOptions): Promise<ScreenshotResult>;
 }
-/** 创建分享模块。 */
+/**
+ * 创建分享模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的分享模块对象。
+ */
 export declare function createShareModule(requester: MiniProgramRequester): MiniProgramShareModule;

package/types/modules/share/screenshot.d.ts

@@ -1,10 +1,16 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramScreenshotOptions } from './types';
-/** 截图分享能力方法名。 */
-export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+export { SHARE_SCREENSHOT_METHOD } from '../../protocol/capabilities';
 /** `share.screenshot` 入参。 */
 export type ScreenshotPayload = MiniProgramScreenshotOptions | undefined;
 /** `share.screenshot` 返回值由客户端协议决定。 */
 export type ScreenshotResult = unknown;
-/** 截图并唤起分享。 */
+/**
+ * 截图并唤起分享。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 截图区域、延迟与保存相册等配置。
+ * @returns 由宿主客户端协议决定的结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
 export declare function screenshot(requester: MiniProgramRequester, options?: MiniProgramScreenshotOptions): Promise<ScreenshotResult>;

package/types/modules/share/show-share-menu.d.ts

@@ -1,10 +1,16 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramShowShareMenuOptions } from './types';
-/** 展示分享面板能力方法名。 */
-export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
+export { SHARE_SHOW_SHARE_MENU_METHOD } from '../../protocol/capabilities';
 /** `share.showShareMenu` 入参。 */
 export type ShowShareMenuPayload = MiniProgramShowShareMenuOptions;
 /** `share.showShareMenu` 返回值由客户端协议决定。 */
 export type ShowShareMenuResult = unknown;
-/** 展示基础分享面板。 */
+/**
+ * 展示基础分享面板。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 基础分享参数。
+ * @returns 由宿主客户端协议决定的结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
 export declare function showShareMenu(requester: MiniProgramRequester, options: ShowShareMenuPayload): Promise<ShowShareMenuResult>;

package/types/modules/share/types.d.ts

@@ -1,6 +1,16 @@
-/** 小程序可选分享渠道。 */
+/**
+ * 小程序可选分享渠道。
+ *
+ * @remarks
+ * 不同宿主环境可支持的渠道集合可能不同；未传 `channel` 时由客户端自行展示默认分享面板。
+ */
 export type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
-/** 展示基础分享面板的配置。 */
+/**
+ * 展示基础分享面板的配置。
+ *
+ * @remarks
+ * 该配置只暴露基础分享字段，不暴露宿主内部上报、回调、自定义按钮等协议参数。
+ */
 export interface MiniProgramShowShareMenuOptions {
     /** 分享标题。 */
     title: string;
@@ -13,7 +23,12 @@ export interface MiniProgramShowShareMenuOptions {
     /** 指定分享渠道；不传则由客户端展示默认分享面板。 */
     channel?: MiniProgramShareChannel;
 }
-/** 截图区域。 */
+/**
+ * 截图区域。
+ *
+ * @remarks
+ * 坐标与尺寸单位均为像素，基于当前小程序可见窗口坐标系。
+ */
 export interface MiniProgramScreenshotRect {
     /** 截图区域左边距。 */
     left: number;
@@ -24,7 +39,12 @@ export interface MiniProgramScreenshotRect {
     /** 截图区域高度。 */
     height: number;
 }
-/** 截图分享配置。 */
+/**
+ * 截图分享配置。
+ *
+ * @remarks
+ * 该配置只暴露截图与保存相册相关基础字段，不暴露宿主内部上传、回调或样式扩展能力。
+ */
 export interface MiniProgramScreenshotOptions {
     /** 指定截图区域；不传则默认截当前可见窗口。 */
     rect?: MiniProgramScreenshotRect;

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

@@ -0,0 +1,56 @@
+import type { MiniProgramRequester } from '../../core/client';
+export { STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD } from '../../protocol/capabilities';
+/** `storage.getStorage` 入参。 */
+export interface GetStoragePayload {
+    /** storage key。 */
+    key: string;
+}
+/**
+ * `storage.getStorage` 返回值。
+ *
+ * @typeParam T 反序列化后的业务数据类型。
+ */
+export interface GetStorageResult<T = unknown> {
+    /** key 对应的数据；不存在时为 undefined。 */
+    data: T | undefined;
+}
+/** `storage.setStorage` 入参。 */
+export interface SetStoragePayload {
+    /** storage key。 */
+    key: string;
+    /** 需要写入的数据。 */
+    data: unknown;
+}
+export type { MiniProgramStorageMethod } from '../../protocol/capabilities';
+/** 外部小程序可调用的 storage 模块。 */
+export interface MiniProgramStorageModule {
+    /** 获取小程序隔离 storage。 */
+    getStorage<T = unknown>(options: GetStoragePayload): Promise<GetStorageResult<T>>;
+    /** 写入小程序隔离 storage。 */
+    setStorage(options: SetStoragePayload): Promise<void>;
+}
+/**
+ * 获取小程序隔离 storage。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 读取的 storage key。
+ * @returns 对应 key 的标准化读取结果。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
+export declare function getStorage<T = unknown>(requester: MiniProgramRequester, options: GetStoragePayload): Promise<GetStorageResult<T>>;
+/**
+ * 写入小程序隔离 storage。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @param options 要写入的 storage key 与数据。
+ * @returns 当写入完成后 resolve。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
+export declare function setStorage(requester: MiniProgramRequester, options: SetStoragePayload): Promise<void>;
+/**
+ * 创建 storage 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的 storage 模块对象。
+ */
+export declare function createStorageModule(requester: MiniProgramRequester): MiniProgramStorageModule;

package/types/modules/user/get-info.d.ts

@@ -1,7 +1,6 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramUserInfoResult } from './types';
-/** 用户信息能力方法名。 */
-export declare const USER_GET_INFO_METHOD: "user.getInfo";
+export { USER_GET_INFO_METHOD } from '../../protocol/capabilities';
 /**
  * `user.getInfo` 不需要入参。
  */
@@ -13,7 +12,12 @@ export type GetUserInfoResult = MiniProgramUserInfoResult;
 /**
  * 获取当前访问小程序用户的公开基础资料。
  *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 当前用户的登录态与公开基础资料。
+ *
  * 该能力只返回 `heybox_id`、`nickname`、`avatar` 三个公开字段。
  * 未登录时不会触发登录流程，直接返回 `{ isLogin: false, userInfo: null }`。
+ *
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主运行时调用失败时抛出。
  */
 export declare function getInfo(requester: MiniProgramRequester): Promise<GetUserInfoResult>;

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

@@ -1,21 +1,19 @@
 import type { MiniProgramRequester } from '../../core/client';
-import { USER_GET_INFO_METHOD, type GetUserInfoResult } from './get-info';
-import { USER_LOGIN_METHOD, type LoginResult } from './login';
+import { type GetUserInfoResult } from './get-info';
 export * from './get-info';
-export * from './login';
 export * from './types';
-/** 用户模块开放的方法名。 */
-export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_LOGIN_METHOD;
+export type { MiniProgramUserMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的用户模块。 */
 export interface MiniProgramUserModule {
     /**
      * 获取当前用户登录态与公开基础资料。
      */
     getInfo(): Promise<GetUserInfoResult>;
-    /**
-     * 唤起登录，并返回登录后的最新用户信息。
-     */
-    login(): Promise<LoginResult>;
 }
-/** 创建用户模块。 */
+/**
+ * 创建用户模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的用户模块对象。
+ */
 export declare function createUserModule(requester: MiniProgramRequester): MiniProgramUserModule;

package/types/modules/user/types.d.ts

@@ -15,6 +15,7 @@ export interface MiniProgramUserInfo {
 /**
  * 用户能力统一返回结构。
  *
+ * @remarks
  * 未登录时 `isLogin` 为 `false`，且 `userInfo` 固定为 `null`。
  * 已登录时 `isLogin` 为 `true`，`userInfo` 为公开基础资料。
  */

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

@@ -0,0 +1,71 @@
+import type { MiniProgramRequester } from '../../core/client';
+/**
+ * 小程序安全区域信息。
+ *
+ * @remarks
+ * 所有字段单位均为像素，基于当前小程序可用窗口坐标系。
+ */
+export interface MiniProgramSafeArea {
+    /** 安全区域左上角横坐标。 */
+    left: number;
+    /** 安全区域右下角横坐标。 */
+    right: number;
+    /** 安全区域左上角纵坐标。 */
+    top: number;
+    /** 安全区域右下角纵坐标。 */
+    bottom: number;
+    /** 安全区域宽度，单位 px。 */
+    width: number;
+    /** 安全区域高度，单位 px。 */
+    height: number;
+}
+/**
+ * 小程序窗口信息。
+ *
+ * @remarks
+ * 该结构统一描述屏幕尺寸、可用窗口尺寸、安全区域与顶部偏移等容器信息。
+ */
+export interface MiniProgramWindowInfoResult {
+    /** 设备像素比。 */
+    pixelRatio: number;
+    /** 屏幕宽度，单位 px。 */
+    screenWidth: number;
+    /** 屏幕高度，单位 px。 */
+    screenHeight: number;
+    /** 可使用窗口宽度，单位 px。 */
+    windowWidth: number;
+    /** 可使用窗口高度，单位 px。 */
+    windowHeight: number;
+    /** 状态栏高度；黑盒环境按顶部可用偏移兼容。 */
+    statusBarHeight: number;
+    /** 安全区域。 */
+    safeArea: MiniProgramSafeArea;
+    /** 窗口上边缘的 y 值。 */
+    screenTop: number;
+}
+export { VIEWPORT_GET_WINDOW_INFO_METHOD } from '../../protocol/capabilities';
+/** `viewport.getWindowInfo` 不需要入参。 */
+export type GetWindowInfoPayload = void;
+/** `viewport.getWindowInfo` 返回当前小程序可用窗口信息。 */
+export type GetWindowInfoResult = MiniProgramWindowInfoResult;
+export type { MiniProgramViewportMethod } from '../../protocol/capabilities';
+/** 外部小程序可调用的 Viewport 模块。 */
+export interface MiniProgramViewportModule {
+    /** 获取当前小程序窗口信息。 */
+    getWindowInfo(): Promise<GetWindowInfoResult>;
+}
+/**
+ * 获取当前小程序窗口信息。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 当前小程序可用窗口信息。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ */
+export declare function getWindowInfo(requester: MiniProgramRequester): Promise<GetWindowInfoResult>;
+/**
+ * 创建 Viewport 模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的 Viewport 模块对象。
+ */
+export declare function createViewportModule(requester: MiniProgramRequester): MiniProgramViewportModule;

package/types/protocol/capabilities.d.ts

@@ -0,0 +1,180 @@
+import type { LoginPayload, LoginResult } from '../modules/auth';
+import type { NetworkRequestPayload, NetworkResponsePayload } from '../modules/network';
+import type { ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult } from '../modules/share';
+import type { GetStoragePayload, GetStorageResult, SetStoragePayload } from '../modules/storage';
+import type { GetUserInfoPayload, GetUserInfoResult } from '../modules/user';
+import type { GetWindowInfoPayload, GetWindowInfoResult } from '../modules/viewport';
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const AUTH_LOGIN_METHOD: "auth.login";
+/**
+ * 用户信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const USER_GET_INFO_METHOD: "user.getInfo";
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const VIEWPORT_GET_WINDOW_INFO_METHOD: "viewport.getWindowInfo";
+/**
+ * 读取小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const STORAGE_GET_STORAGE_METHOD: "storage.getStorage";
+/**
+ * 写入小程序隔离 storage 能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const STORAGE_SET_STORAGE_METHOD: "storage.setStorage";
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const NETWORK_REQUEST_METHOD: "network.request";
+/** 授权模块开放的方法名。 */
+export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
+/** 用户模块开放的方法名。 */
+export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD;
+/** 分享模块开放的方法名。 */
+export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
+/** Viewport 模块开放的方法名。 */
+export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD;
+/** Storage 模块开放的方法名。 */
+export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
+/** 网络模块开放的方法名。 */
+export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD;
+/** 父容器开放给小程序调用的 bridge method。 */
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod;
+/** 小程序开放能力所属模块。 */
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network';
+/** 小程序开放能力风险级别，用于权限、审计和灰度策略。 */
+export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
+/**
+ * 小程序开放能力定义。
+ *
+ * @remarks
+ * 这是 SDK 与 runtime 共享的能力目录元数据。runtime 可以在此基础上绑定 handler，
+ * 但 method、module、capability、permission 与 risk 不应在 runtime 侧重复维护。
+ */
+export interface MiniProgramCapabilityDefinition {
+    /** bridge method exposed to iframe SDK. */
+    method: MiniProgramBridgeMethod;
+    /** Module that owns this capability. */
+    module: MiniProgramCapabilityModule;
+    /** Runtime instance switch key. */
+    capability: MiniProgramBridgeMethod;
+    /** Platform permission key reserved for mini-program level authorization. */
+    permission: string;
+    /** Audit / rollout hint for policy composition. */
+    risk: MiniProgramCapabilityRisk;
+}
+/**
+ * 小程序开放能力目录。
+ *
+ * @remarks
+ * 新增 bridge method 时应先更新这里，再分别补齐 SDK 模块、runtime handler 与测试。
+ */
+export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
+    readonly method: "auth.login";
+    readonly module: "auth";
+    readonly capability: "auth.login";
+    readonly permission: "auth.login";
+    readonly risk: "medium";
+}, {
+    readonly method: "user.getInfo";
+    readonly module: "user";
+    readonly capability: "user.getInfo";
+    readonly permission: "user.getInfo";
+    readonly risk: "medium";
+}, {
+    readonly method: "share.showShareMenu";
+    readonly module: "share";
+    readonly capability: "share.showShareMenu";
+    readonly permission: "share.basic";
+    readonly risk: "low";
+}, {
+    readonly method: "share.screenshot";
+    readonly module: "share";
+    readonly capability: "share.screenshot";
+    readonly permission: "share.screenshot";
+    readonly risk: "medium";
+}, {
+    readonly method: "viewport.getWindowInfo";
+    readonly module: "viewport";
+    readonly capability: "viewport.getWindowInfo";
+    readonly permission: "viewport.windowInfo";
+    readonly risk: "low";
+}, {
+    readonly method: "storage.getStorage";
+    readonly module: "storage";
+    readonly capability: "storage.getStorage";
+    readonly permission: "storage.read";
+    readonly risk: "low";
+}, {
+    readonly method: "storage.setStorage";
+    readonly module: "storage";
+    readonly capability: "storage.setStorage";
+    readonly permission: "storage.write";
+    readonly risk: "medium";
+}, {
+    readonly method: "network.request";
+    readonly module: "network";
+    readonly capability: "network.request";
+    readonly permission: "network.request";
+    readonly risk: "high";
+}];
+/** bridge method 到请求 payload 的映射。 */
+export interface MiniProgramCapabilityPayloadMap {
+    [AUTH_LOGIN_METHOD]: LoginPayload;
+    [USER_GET_INFO_METHOD]: GetUserInfoPayload;
+    [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuPayload;
+    [SHARE_SCREENSHOT_METHOD]: ScreenshotPayload;
+    [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoPayload;
+    [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
+    [STORAGE_SET_STORAGE_METHOD]: SetStoragePayload;
+    [NETWORK_REQUEST_METHOD]: NetworkRequestPayload;
+}
+/** bridge method 到标准化响应 payload 的映射。 */
+export interface MiniProgramCapabilityResultMap {
+    [AUTH_LOGIN_METHOD]: LoginResult;
+    [USER_GET_INFO_METHOD]: GetUserInfoResult;
+    [SHARE_SHOW_SHARE_MENU_METHOD]: ShowShareMenuResult;
+    [SHARE_SCREENSHOT_METHOD]: ScreenshotResult;
+    [VIEWPORT_GET_WINDOW_INFO_METHOD]: GetWindowInfoResult;
+    [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;
+    [STORAGE_SET_STORAGE_METHOD]: void;
+    [NETWORK_REQUEST_METHOD]: NetworkResponsePayload;
+}
+/** 指定 bridge method 的请求 payload。 */
+export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];
+/** 指定 bridge method 的标准化响应 payload。 */
+export type MiniProgramCapabilityResult<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityResultMap[T];

package/types/protocol/guards.d.ts

@@ -1,3 +1,8 @@
 import type { MiniProgramBridgeMessage } from './types';
-/** 判断未知数据是否符合小程序 bridge 消息信封。 */
+/**
+ * 判断未知数据是否符合小程序 bridge 消息信封。
+ *
+ * @param value 待判断的未知数据。
+ * @returns 当数据满足小程序 bridge 消息基础结构时返回 `true`。
+ */
 export declare function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage;

package/types/protocol/types.d.ts

@@ -1,8 +1,18 @@
 import type { MiniProgramUserInfoResult } from '../modules/user/types';
 import type { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION } from './constants';
-/** 小程序沙盒消息类型。 */
+/**
+ * 小程序沙盒消息类型。
+ *
+ * @remarks
+ * 当前协议区分握手、请求、响应与事件四类消息。
+ */
 export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event';
-/** 首版开放给外部小程序监听的生命周期与业务事件名。 */
+/**
+ * 首版开放给外部小程序监听的生命周期与业务事件名。
+ *
+ * @remarks
+ * `on/off` 会基于该联合类型约束可监听的事件集合。
+ */
 export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'authChange';
 /**
  * bridge 错误结构。
@@ -20,7 +30,7 @@ export interface MiniProgramBridgeError {
 /**
  * SDK 与沙盒之间统一的 postMessage 信封。
  *
- * 由于 iframe sandbox 不启用 `allow-same-origin`，协议不依赖 origin 校验，
+ * 当前 iframe sandbox 即使启用了 `allow-same-origin`，协议也不把 origin 当作信任依据，
  * 而是由父容器校验 `event.source === iframe.contentWindow` 与实例 nonce。
  */
 export interface MiniProgramBridgeMessage<TPayload = unknown> {
@@ -83,5 +93,10 @@ export interface MiniProgramEventPayloadMap {
     /** 登录状态发生变化后的最新用户信息。 */
     authChange: MiniProgramUserInfoResult;
 }
-/** 小程序事件监听函数。 */
+/**
+ * 小程序事件监听函数。
+ *
+ * @typeParam T 要监听的事件名。
+ * @param payload 对应事件的标准化载荷。
+ */
 export type MiniProgramEventHandler<T extends MiniProgramEventName = MiniProgramEventName> = (payload: MiniProgramEventPayloadMap[T]) => void;