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

package/types/core/client.d.ts

@@ -1,4 +1,5 @@
 import { type MiniProgramSDKHandshakeState, type MiniProgramSDKHandshakeStateHandler } from './handshake-state';
+import { type MiniProgramEnvironmentInfo, type MiniProgramEnvironmentReader } from '../modules/environment';
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityPayload, MiniProgramCapabilityResult } from '../protocol/capabilities';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 /**
@@ -36,7 +37,7 @@ 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 MiniProgramOperationRequester {
+export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester, MiniProgramEnvironmentReader {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
@@ -61,6 +62,7 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     private destroyed;
     private runtimeUnavailable;
     private runtimeUnavailableError?;
+    private environmentInfo?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     waitForHandshake(): Promise<void>;
@@ -68,6 +70,10 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     getHandshakeState(): MiniProgramSDKHandshakeState;
     /** 订阅握手状态，并立即接收当前状态。 */
     onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
+    /** 等待握手后读取当前实例的环境快照。 */
+    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
     /** 注册小程序事件监听。 */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /** 移除小程序事件监听。 */

package/types/core/sdk.d.ts

@@ -9,6 +9,7 @@ import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
 import { type MiniProgramUiModule } from '../modules/ui';
 import { type MiniProgramDeviceModule } from '../modules/device';
+import { type MiniProgramEnvironmentModule } from '../modules/environment';
 import { type MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -48,6 +49,8 @@ export declare class MiniProgramSDK {
     readonly navigation: MiniProgramNavigationModule;
     /** 云端数据相关开放能力。 */
     readonly cloud: MiniProgramCloudModule;
+    /** 当前实例的环境信息。 */
+    readonly environment: MiniProgramEnvironmentModule;
     constructor(options?: MiniProgramSDKOptions);
     /** 获取当前握手状态。 */
     getHandshakeState(): MiniProgramSDKHandshakeState;

package/types/core/singleton.d.ts

@@ -8,6 +8,7 @@ import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
 import type { MiniProgramUiModule } from '../modules/ui';
 import type { MiniProgramDeviceModule } from '../modules/device';
+import type { MiniProgramEnvironmentModule } from '../modules/environment';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -103,5 +104,7 @@ export declare const device: MiniProgramDeviceModule;
 export declare const navigation: MiniProgramNavigationModule;
 /** 默认 SDK 实例的 cloud 模块。 */
 export declare const cloud: MiniProgramCloudModule;
+/** 默认 SDK 实例的 environment 模块。 */
+export declare const environment: MiniProgramEnvironmentModule;
 /** 重置默认 SDK 实例，仅用于测试。 */
 export declare function resetDefaultSDKForTest(): void;

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, files, network, ui, device, navigation, cloud, } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, environment, 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';
@@ -14,6 +14,7 @@ export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgra
 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 { MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramOperatingSystemName, MiniProgramRuntimeMode, } from './modules/environment';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
 import { getHandshakeState, off, on, onHandshakeStateChange } from './core/singleton';
 declare const hbSDK: {
@@ -30,6 +31,7 @@ declare const hbSDK: {
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;
+    environment: import(".").MiniProgramEnvironmentModule;
     navigation: import(".").MiniProgramNavigationModule;
     cloud: import(".").MiniProgramCloudModule;
 };

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

@@ -0,0 +1,70 @@
+import type { MiniProgramOperatingSystemName, MiniProgramRuntimeMode } from '@heybox/hb-sdk-protocol';
+/** 小程序环境信息中的运行模式。 */
+export type { MiniProgramRuntimeMode } from '@heybox/hb-sdk-protocol';
+/** 小程序环境信息中的操作系统名称。 */
+export type { MiniProgramOperatingSystemName } from '@heybox/hb-sdk-protocol';
+/** 当前小程序实例的只读环境快照。 */
+export interface MiniProgramEnvironmentInfo {
+    readonly runtime: {
+        readonly mode: MiniProgramRuntimeMode;
+    };
+    readonly host: {
+        readonly appVersion: string | null;
+    };
+    readonly miniProgram: {
+        readonly id: string | null;
+        readonly version: string | null;
+    };
+    readonly operatingSystem: {
+        readonly name: MiniProgramOperatingSystemName;
+        readonly version: string | null;
+    };
+    readonly sdk: {
+        readonly version: string;
+    };
+}
+/** SDK 内部读取环境快照所需的最小能力。 */
+export interface MiniProgramEnvironmentReader {
+    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
+    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
+}
+/** 外部小程序可调用的 environment 模块。 */
+export interface MiniProgramEnvironmentModule {
+    /**
+     * 获取当前小程序实例的环境快照，并在必要时自动等待 SDK 握手。
+     *
+     * @since 0.8.1-alpha.2
+     * @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(): Promise<MiniProgramEnvironmentInfo>;
+    /**
+     * 同步读取握手完成后缓存的环境快照。
+     *
+     * @throws {@link HbMiniProgramSDKError} SDK 尚未 ready 时抛出 `ENVIRONMENT_NOT_READY`。
+     * @since 0.8.1-alpha.2
+     * @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
+     */
+    getInfoSync(): MiniProgramEnvironmentInfo;
+}
+/** 创建环境信息模块。 */
+export declare function createEnvironmentModule(reader: MiniProgramEnvironmentReader): MiniProgramEnvironmentModule;
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+export declare function normalizeMiniProgramEnvironmentInfo(value: unknown): MiniProgramEnvironmentInfo;

package/types/protocol.d.ts

@@ -1,5 +1,5 @@
 export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramByteArray, isMiniProgramBridgeMessage, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions, } from '@heybox/hb-sdk-protocol';
-export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
+export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramRuntimePermissionEntry, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
 export type { LoginOptions } from './modules/auth';
 export type { GetSteamGameListOptions } from './modules/user';
 export type { MiniProgramEventHandler } from './protocol/types';