@heybox/hb-sdk 0.1.2 → 0.2.0-alpha.0

package/types/core/client.d.ts

@@ -1,5 +1,10 @@
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/** 创建 SDK bridge client 的配置项。 */
+/**
+ * 创建 SDK bridge client 的配置项。
+ *
+ * @remarks
+ * 该配置主要用于独立实例、自定义宿主环境注入和测试场景。
+ */
 export interface MiniProgramSDKOptions {
     /** 请求与握手超时时间，单位毫秒。 */
     timeout?: number;
@@ -9,10 +14,24 @@ export interface MiniProgramSDKOptions {
     selfWindow?: Window;
     /** 父窗口，测试环境可注入；显式传 null 可模拟非 iframe 环境。 */
     targetWindow?: Window | null;
+    /** 精准 postMessage 目标 origin；未传时尝试推断，失败则回退为 `*`。 */
+    targetOrigin?: string;
 }
-/** 模块 API 发起请求所需的最小能力。 */
+/**
+ * 模块 API 发起请求所需的最小能力。
+ *
+ * @remarks
+ * 各公开模块只依赖该最小接口发起 bridge 请求，以保持模块层与底层实现解耦。
+ */
 export interface MiniProgramRequester {
-    /** 向父容器调用指定开放能力。 */
+    /**
+     * 向父容器调用指定开放能力。
+     *
+     * @typeParam T 标准化后的返回值类型。
+     * @param method bridge method 名称。
+     * @param payload 可序列化请求载荷。
+     * @returns 由父容器返回的标准化结果。
+     */
     request<T>(method: string, payload?: unknown): Promise<T>;
 }
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
@@ -20,6 +39,7 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
+    private readonly targetOrigin;
     private readonly nonce;
     private readonly pendingRequests;
     private readonly eventBus;
@@ -30,6 +50,8 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     private resolveReady;
     private rejectReady;
     private readyTimer?;
+    private handshakeRetryTimer?;
+    private destroyed;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     ready(): Promise<void>;
@@ -42,12 +64,13 @@ export declare class MiniProgramBridgeClient implements MiniProgramRequester {
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy(): void;
     private ensureStarted;
+    private postHandshake;
     private onMessage;
     private handleEvent;
     private handleResponse;
     private postMessage;
     private resolveReadyOnce;
     private failReady;
-    private clearReadyTimer;
+    private clearReadyTimers;
     private rejectAllPending;
 }

package/types/core/errors.d.ts

@@ -1,5 +1,13 @@
 import type { MiniProgramBridgeError } from '../protocol/types';
-/** SDK 对外抛出的标准错误类型。 */
+import type { MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse } from '../modules/network';
+/**
+ * SDK 对外抛出的标准 bridge / runtime 错误类型。
+ *
+ * @remarks
+ * 该错误用于表示握手失败、bridge 调用失败、父容器运行时错误等
+ * 非 HTTP 结果错误。其 `code` 字段可用于业务分支处理，
+ * `data` 仅作为可选调试信息，不保证结构稳定。
+ */
 export declare class HbMiniProgramSDKError extends Error {
     /** 稳定错误码。 */
     code: string;
@@ -7,5 +15,40 @@ export declare class HbMiniProgramSDKError extends Error {
     data?: unknown;
     constructor(error: MiniProgramBridgeError);
 }
-/** 创建 SDK 标准错误。 */
+/**
+ * 创建 SDK 标准错误。
+ *
+ * @param code 稳定错误码。
+ * @param message 面向开发者的错误说明。
+ * @param data 可选调试数据。
+ * @returns 标准化 `HbMiniProgramSDKError` 实例。
+ *
+ * @remarks
+ * 仅供 SDK 内部或同仓运行时层统一构造 bridge / runtime 错误。
+ */
 export declare function createSDKError(code: string, message: string, data?: unknown): HbMiniProgramSDKError;
+/**
+ * SDK 对外抛出的 HTTP 错误类型。
+ *
+ * @remarks
+ * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
+ * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
+ *
+ * @typeParam T 标准化响应数据的类型。
+ */
+export declare class HbMiniProgramNetworkError<T = unknown> extends Error {
+    /** HTTP 状态码。 */
+    status: number;
+    /** 标准化响应数据。 */
+    data: T;
+    /** 标准化响应头。 */
+    headers: Record<string, string>;
+    /** SDK 公共请求配置快照。 */
+    config: MiniProgramNetworkRequestConfig;
+    /** 完整标准化响应。 */
+    response: MiniProgramNetworkResponse<T>;
+    /**
+     * @param response 已完成请求的标准化网络响应。
+     */
+    constructor(response: MiniProgramNetworkResponse<T>);
+}

package/types/core/sdk.d.ts

@@ -1,26 +1,94 @@
 import { type MiniProgramSDKOptions } from './client';
+import { type MiniProgramAuthModule } from '../modules/auth';
 import { type MiniProgramShareModule } from '../modules/share';
+import { type MiniProgramStorageModule } from '../modules/storage';
+import { type MiniProgramNetworkModule } from '../modules/network';
+import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
-import { type MiniProgramSystemModule } from '../modules/system';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/** 外部小程序 SDK 实例。 */
+/**
+ * 外部小程序 SDK 实例。
+ *
+ * @remarks
+ * 该实例负责组织授权、用户、分享、容器、存储与网络等开放能力，并维护
+ * iframe 内小程序与父容器之间的 bridge 生命周期。
+ *
+ * 多数业务页直接使用默认单例即可；只有在测试、多实例或需要定制运行参数时，
+ * 才建议显式创建独立实例。
+ *
+ * @example
+ * ```ts
+ * import { createMiniProgramSDK } from '@heybox/hb-sdk'
+ *
+ * const sdk = createMiniProgramSDK({
+ *   timeout: 15000,
+ * })
+ *
+ * await sdk.ready()
+ * ```
+ */
 export declare class MiniProgramSDK {
     private readonly client;
-    /** 用户相关开放能力。 */
+    /** 授权相关开放能力。 */
+    readonly auth: MiniProgramAuthModule;
+    /** 用户资料相关开放能力。 */
     readonly user: MiniProgramUserModule;
     /** 分享相关开放能力。 */
     readonly share: MiniProgramShareModule;
-    /** 系统相关开放能力。 */
-    readonly system: MiniProgramSystemModule;
+    /** 视口相关开放能力。 */
+    readonly viewport: MiniProgramViewportModule;
+    /** Storage 相关开放能力。 */
+    readonly storage: MiniProgramStorageModule;
+    /** 网络请求相关开放能力。 */
+    readonly network: MiniProgramNetworkModule;
     constructor(options?: MiniProgramSDKOptions);
-    /** 等待 SDK 与父容器完成握手。 */
+    /**
+     * 等待 SDK 与父容器完成握手。
+     *
+     * @returns 当 bridge 握手成功后 resolve。
+     * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
+     */
     ready(): Promise<void>;
-    /** 注册小程序生命周期或业务事件。 */
+    /**
+     * 注册小程序生命周期或业务事件。
+     *
+     * @param eventName 要监听的事件名。
+     * @param handler 事件处理函数。
+     * @returns 事件解绑函数。
+     */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-    /** 移除小程序生命周期或业务事件。 */
+    /**
+     * 移除小程序生命周期或业务事件。
+     *
+     * @param eventName 要移除的事件名。
+     * @param handler 对应的事件处理函数。
+     */
     off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-    /** 销毁 SDK 实例。 */
+    /**
+     * 销毁 SDK 实例。
+     *
+     * @remarks
+     * 销毁后会移除 message 监听，并拒绝尚未完成的 bridge 请求。
+     * 已销毁实例不应继续复用。
+     */
     destroy(): void;
 }
-/** 创建独立 SDK 实例，主要用于测试或多实例场景。 */
+/**
+ * 创建独立 SDK 实例。
+ *
+ * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
+ *
+ * @remarks
+ * 适用于测试、多实例场景，或需要自定义 `timeout`、`targetWindow` 等运行参数的场景。
+ *
+ * @example
+ * ```ts
+ * import { createMiniProgramSDK } from '@heybox/hb-sdk'
+ *
+ * const sdk = createMiniProgramSDK({
+ *   timeout: 15000,
+ * })
+ * ```
+ */
 export declare function createMiniProgramSDK(options?: MiniProgramSDKOptions): MiniProgramSDK;

package/types/core/singleton.d.ts

@@ -1,18 +1,44 @@
+import type { MiniProgramAuthModule } from '../modules/auth';
 import type { MiniProgramShareModule } from '../modules/share';
+import type { MiniProgramStorageModule } from '../modules/storage';
+import type { MiniProgramNetworkModule } from '../modules/network';
+import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
-import type { MiniProgramSystemModule } from '../modules/system';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
-/** 等待默认 SDK 实例与父容器完成握手。 */
+/**
+ * 等待默认 SDK 实例与父容器完成握手。
+ *
+ * @returns 当默认 SDK 单例与父容器握手成功后 resolve。
+ * @throws {HbMiniProgramSDKError} 当当前页面不在 iframe 中、缺少 nonce 或握手超时时抛出。
+ */
 export declare function ready(): Promise<void>;
-/** 注册默认 SDK 实例的事件监听。 */
+/**
+ * 注册默认 SDK 实例的事件监听。
+ *
+ * @param eventName 要监听的事件名。
+ * @param handler 事件处理函数。
+ * @returns 事件解绑函数。
+ */
 export declare function on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
-/** 移除默认 SDK 实例的事件监听。 */
+/**
+ * 移除默认 SDK 实例的事件监听。
+ *
+ * @param eventName 要移除的事件名。
+ * @param handler 对应的事件处理函数。
+ * @returns 无返回值。
+ */
 export declare function off<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): void;
-/** 默认 SDK 实例的用户模块。 */
+/** 默认 SDK 实例的授权模块。 */
+export declare const auth: MiniProgramAuthModule;
+/** 默认 SDK 实例的用户资料模块。 */
 export declare const user: MiniProgramUserModule;
 /** 默认 SDK 实例的分享模块。 */
 export declare const share: MiniProgramShareModule;
-/** 默认 SDK 实例的系统模块。 */
-export declare const system: MiniProgramSystemModule;
+/** 默认 SDK 实例的 Viewport 模块。 */
+export declare const viewport: MiniProgramViewportModule;
+/** 默认 SDK 实例的 storage 模块。 */
+export declare const storage: MiniProgramStorageModule;
+/** 默认 SDK 实例的 network 模块。 */
+export declare const network: MiniProgramNetworkModule;
 /** 重置默认 SDK 实例，仅用于测试。 */
 export declare function resetDefaultSDKForTest(): void;

package/types/core/utils.d.ts

@@ -2,6 +2,8 @@
 export declare function getGlobalWindow(): Window | undefined;
 /** 获取父窗口；非 iframe 环境返回 null。 */
 export declare function getParentWindow(currentWindow?: Window): Window | null;
+/** 尝试读取父窗口 origin；跨域读取失败时回退到 document.referrer。 */
+export declare function readParentOrigin(currentWindow?: Window): string;
 /** 从父容器注入到 URL 的 query 中读取 bridge nonce。 */
 export declare function readBridgeNonce(currentWindow?: Window): string;
 /** 创建请求 ID。 */

package/types/index.d.ts

@@ -1,20 +1,26 @@
 export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
-export { HbMiniProgramSDKError } from './core/errors';
+export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
 export type { MiniProgramRequester, MiniProgramSDKOptions } from './core/client';
-export { ready, on, off, user, share, system } from './core/singleton';
+export { ready, on, off, auth, user, share, viewport, storage, network } from './core/singleton';
 export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, SDK_HANDSHAKE_METHOD, } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
 export type { MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, } from './protocol/types';
+export * from './modules/auth';
 export * from './modules/user';
 export * from './modules/share';
-export * from './modules/system';
+export * from './modules/viewport';
+export * from './modules/storage';
+export * from './modules/network';
 import { off, on, ready } from './core/singleton';
 declare const hbSDK: {
     ready: typeof ready;
     on: typeof on;
     off: typeof off;
+    auth: import(".").MiniProgramAuthModule;
     user: import(".").MiniProgramUserModule;
     share: import(".").MiniProgramShareModule;
-    system: import(".").MiniProgramSystemModule;
+    viewport: import(".").MiniProgramViewportModule;
+    storage: import(".").MiniProgramStorageModule;
+    network: import(".").MiniProgramNetworkModule;
 };
 export default hbSDK;

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

@@ -0,0 +1,42 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramUserInfoResult } from '../user';
+/**
+ * 登录授权能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const AUTH_LOGIN_METHOD: "auth.login";
+/** `auth.login` 不需要入参。 */
+export type LoginPayload = void;
+/** `auth.login` 返回登录流程结束后的最新用户登录态与公开基础资料。 */
+export type LoginResult = MiniProgramUserInfoResult;
+/** 授权模块开放的方法名。 */
+export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
+/** 外部小程序可调用的授权模块。 */
+export interface MiniProgramAuthModule {
+    /**
+     * 唤起登录授权，并返回登录后的最新用户信息。
+     *
+     * 该能力不会向小程序暴露 token、cookie 或任何登录凭据。
+     */
+    login(): Promise<LoginResult>;
+}
+/**
+ * 唤起登录授权，并在流程返回后刷新用户公开基础资料。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 登录流程完成后的最新用户登录态与公开资料。
+ * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主运行时调用失败时抛出。
+ *
+ * @remarks
+ * 该能力不会向小程序暴露 token、cookie 或其他登录凭据。
+ */
+export declare function login(requester: MiniProgramRequester): Promise<LoginResult>;
+/**
+ * 创建授权模块。
+ *
+ * @param requester 底层 bridge 请求能力。
+ * @returns 面向业务层的授权模块对象。
+ */
+export declare function createAuthModule(requester: MiniProgramRequester): MiniProgramAuthModule;

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

@@ -0,0 +1,125 @@
+import type { MiniProgramRequester } from '../../core/client';
+/**
+ * 发起网络请求能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const NETWORK_REQUEST_METHOD: "network.request";
+/** `network.request` 请求头。 */
+export type MiniProgramNetworkHeaders = Record<string, string>;
+/** `network.request` 查询参数。 */
+export type MiniProgramNetworkParams = Record<string, unknown>;
+/**
+ * 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?: string;
+    /** 查询参数，会被编码到请求 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?: string;
+    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 = typeof NETWORK_REQUEST_METHOD;
+/** 外部小程序可调用的网络模块。 */
+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

@@ -5,7 +5,12 @@ import type { MiniProgramScreenshotOptions } from './types';
 export * from './screenshot';
 export * from './show-share-menu';
 export * from './types';
-/** 分享模块开放的方法名。 */
+/**
+ * 分享模块开放的方法名。
+ *
+ * @remarks
+ * 该联合类型用于约束分享模块向父容器发起的 bridge method 集合。
+ */
 export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
 /** 外部小程序可调用的分享模块。 */
 export interface MiniProgramShareModule {
@@ -14,5 +19,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,22 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramScreenshotOptions } from './types';
-/** 截图分享能力方法名。 */
+/**
+ * 截图分享能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
 export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
 /** `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,22 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramShowShareMenuOptions } from './types';
-/** 展示分享面板能力方法名。 */
+/**
+ * 展示分享面板能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
 export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
 /** `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;