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

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

@@ -1,21 +1,25 @@
 import type { MiniProgramRequester } from '../../core/client';
 import { USER_GET_INFO_METHOD, type GetUserInfoResult } from './get-info';
-import { USER_LOGIN_METHOD, type LoginResult } from './login';
 export * from './get-info';
-export * from './login';
 export * from './types';
-/** 用户模块开放的方法名。 */
-export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_LOGIN_METHOD;
+/**
+ * 用户模块开放的方法名。
+ *
+ * @remarks
+ * 该联合类型用于约束用户模块向父容器发起的 bridge method 集合。
+ */
+export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD;
 /** 外部小程序可调用的用户模块。 */
 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,78 @@
+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;
+}
+/**
+ * 视口窗口信息能力方法名。
+ *
+ * @remarks
+ * 供 SDK 与父容器 runtime 共享同一 bridge method 标识。
+ */
+export declare const VIEWPORT_GET_WINDOW_INFO_METHOD: "viewport.getWindowInfo";
+/** `viewport.getWindowInfo` 不需要入参。 */
+export type GetWindowInfoPayload = void;
+/** `viewport.getWindowInfo` 返回当前小程序可用窗口信息。 */
+export type GetWindowInfoResult = MiniProgramWindowInfoResult;
+/** Viewport 模块开放的方法名。 */
+export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD;
+/** 外部小程序可调用的 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/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;

package/types/protocol.d.ts

@@ -0,0 +1,18 @@
+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 { AUTH_LOGIN_METHOD } from './modules/auth';
+export type { LoginPayload, LoginResult, MiniProgramAuthMethod } from './modules/auth';
+export { USER_GET_INFO_METHOD } from './modules/user';
+export type { GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, MiniProgramUserMethod, } from './modules/user';
+export { SHARE_SCREENSHOT_METHOD } from './modules/share/screenshot';
+export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
+export { SHARE_SHOW_SHARE_MENU_METHOD } from './modules/share/show-share-menu';
+export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';
+export type { MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramShowShareMenuOptions, } from './modules/share';
+export { STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, } from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, MiniProgramStorageMethod, SetStoragePayload, } from './modules/storage';
+export { VIEWPORT_GET_WINDOW_INFO_METHOD } from './modules/viewport';
+export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramSafeArea, MiniProgramViewportMethod, MiniProgramWindowInfoResult, } from './modules/viewport';
+export { NETWORK_REQUEST_METHOD } from './modules/network';
+export type { MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';

package/types/modules/system/get-storage.d.ts

@@ -1,15 +0,0 @@
-import type { MiniProgramRequester } from '../../core/client';
-/** 获取小程序隔离 storage 能力方法名。 */
-export declare const SYSTEM_GET_STORAGE_METHOD: "system.getStorage";
-/** `system.getStorage` 入参。 */
-export interface GetStoragePayload {
-    /** storage key。 */
-    key: string;
-}
-/** `system.getStorage` 返回值。 */
-export interface GetStorageResult<T = unknown> {
-    /** key 对应的数据；不存在时为 undefined。 */
-    data: T | undefined;
-}
-/** 获取小程序隔离 storage。 */
-export declare function getStorage<T = unknown>(requester: MiniProgramRequester, options: GetStoragePayload): Promise<GetStorageResult<T>>;

package/types/modules/system/get-window-info.d.ts

@@ -1,16 +0,0 @@
-import type { MiniProgramRequester } from '../../core/client';
-import type { MiniProgramWindowInfoResult } from './types';
-/** 系统窗口信息能力方法名。 */
-export declare const SYSTEM_GET_WINDOW_INFO_METHOD: "system.getWindowInfo";
-/**
- * `system.getWindowInfo` 不需要入参。
- */
-export type GetWindowInfoPayload = void;
-/**
- * `system.getWindowInfo` 返回当前小程序可用窗口信息。
- */
-export type GetWindowInfoResult = MiniProgramWindowInfoResult;
-/**
- * 获取当前小程序窗口信息。
- */
-export declare function getWindowInfo(requester: MiniProgramRequester): Promise<GetWindowInfoResult>;

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

@@ -1,23 +0,0 @@
-import type { MiniProgramRequester } from '../../core/client';
-import { SYSTEM_GET_WINDOW_INFO_METHOD, type GetWindowInfoResult } from './get-window-info';
-import { SYSTEM_GET_STORAGE_METHOD, type GetStoragePayload, type GetStorageResult } from './get-storage';
-import { SYSTEM_SET_STORAGE_METHOD, type SetStoragePayload } from './set-storage';
-export * from './get-window-info';
-export * from './get-storage';
-export * from './set-storage';
-export * from './types';
-/** 系统模块开放的方法名。 */
-export type MiniProgramSystemMethod = typeof SYSTEM_GET_WINDOW_INFO_METHOD | typeof SYSTEM_GET_STORAGE_METHOD | typeof SYSTEM_SET_STORAGE_METHOD;
-/** 外部小程序可调用的系统模块。 */
-export interface MiniProgramSystemModule {
-    /**
-     * 获取当前小程序窗口信息。
-     */
-    getWindowInfo(): Promise<GetWindowInfoResult>;
-    /** 获取小程序隔离 storage。 */
-    getStorage<T = unknown>(options: GetStoragePayload): Promise<GetStorageResult<T>>;
-    /** 写入小程序隔离 storage。 */
-    setStorage(options: SetStoragePayload): Promise<void>;
-}
-/** 创建系统模块。 */
-export declare function createSystemModule(requester: MiniProgramRequester): MiniProgramSystemModule;

package/types/modules/system/set-storage.d.ts

@@ -1,12 +0,0 @@
-import type { MiniProgramRequester } from '../../core/client';
-/** 写入小程序隔离 storage 能力方法名。 */
-export declare const SYSTEM_SET_STORAGE_METHOD: "system.setStorage";
-/** `system.setStorage` 入参。 */
-export interface SetStoragePayload {
-    /** storage key。 */
-    key: string;
-    /** 需要写入的数据。 */
-    data: unknown;
-}
-/** 写入小程序隔离 storage。 */
-export declare function setStorage(requester: MiniProgramRequester, options: SetStoragePayload): Promise<void>;

package/types/modules/system/types.d.ts

@@ -1,34 +0,0 @@
-/** 小程序安全区域信息。 */
-export interface MiniProgramSafeArea {
-    /** 安全区域左上角横坐标。 */
-    left: number;
-    /** 安全区域右下角横坐标。 */
-    right: number;
-    /** 安全区域左上角纵坐标。 */
-    top: number;
-    /** 安全区域右下角纵坐标。 */
-    bottom: number;
-    /** 安全区域宽度，单位 px。 */
-    width: number;
-    /** 安全区域高度，单位 px。 */
-    height: number;
-}
-/** 小程序窗口信息。 */
-export interface MiniProgramWindowInfoResult {
-    /** 设备像素比。 */
-    pixelRatio: number;
-    /** 屏幕宽度，单位 px。 */
-    screenWidth: number;
-    /** 屏幕高度，单位 px。 */
-    screenHeight: number;
-    /** 可使用窗口宽度，单位 px。 */
-    windowWidth: number;
-    /** 可使用窗口高度，单位 px。 */
-    windowHeight: number;
-    /** 状态栏高度；黑盒环境按顶部可用偏移兼容。 */
-    statusBarHeight: number;
-    /** 安全区域。 */
-    safeArea: MiniProgramSafeArea;
-    /** 窗口上边缘的 y 值。 */
-    screenTop: number;
-}

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

@@ -1,18 +0,0 @@
-import type { MiniProgramRequester } from '../../core/client';
-import type { MiniProgramUserInfoResult } from './types';
-/** 用户登录能力方法名。 */
-export declare const USER_LOGIN_METHOD: "user.login";
-/**
- * `user.login` 不需要入参。
- */
-export type LoginPayload = void;
-/**
- * `user.login` 返回登录流程结束后的最新用户登录态与公开基础资料。
- */
-export type LoginResult = MiniProgramUserInfoResult;
-/**
- * 唤起黑盒登录流程，并在流程返回后刷新用户公开基础资料。
- *
- * 该能力不会向小程序暴露 token、cookie 或任何登录凭据。
- */
-export declare function login(requester: MiniProgramRequester): Promise<LoginResult>;