@heybox/hb-sdk 0.9.4-alpha.5 → 0.9.4

package/types/index.d.ts

@@ -1,5 +1,5 @@
-import { MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramBridgeError, MiniProgramRuntimeMode, MiniProgramOperatingSystemName, LoginScope as LoginScope$1, AccountState, MiniProgramUserInfoResult, SetDisplayPayload, SetDisplayResult, WorkspaceCardsRefreshOptions, WorkspaceCardLaunchContext, CompanionExit, CompanionNotificationCategory, CompanionPrepareProgress, CompanionTarget, CompanionCapability, CompanionInfo, CompanionPreparationStatus, ExecuteProtocolInput } from '@heybox/hb-sdk-protocol';
-export { AccountState, AuthorizedUserInfo, CompanionCapability, CompanionExit, CompanionInfo, CompanionNotificationCategory, CompanionPreparationStatus, CompanionPrepareProgress, CompanionTarget, ExecuteProtocolInput, ExecuteProtocolObject, ExecuteProtocolResult, MiniProgramDisplayState, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramOperatingSystemName, MiniProgramOrientationMode, MiniProgramRuntimeMode, MiniProgramUserInfoResult, SetDisplayPayload, SetDisplayResult, USER_INFO_AUTHORIZATION_SCOPES, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, WorkspaceCardLaunchContext, WorkspaceCardsRefreshOptions } from '@heybox/hb-sdk-protocol';
+import { MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramBridgeError, MiniProgramRuntimeMode, MiniProgramOperatingSystemName, LoginScope as LoginScope$1, AccountState, MiniProgramUserInfoResult, SetDisplayPayload, SetDisplayResult, WorkspaceCardsRefreshOptions, WorkspaceCardLaunchContext, GameSaveFileInfo as GameSaveFileInfo$1, GameSaveInfo as GameSaveInfo$1, GameSaveStructuredData, CompanionExit, CompanionNotificationCategory, CompanionPrepareProgress, CompanionTarget, CompanionCapability, CompanionInfo, CompanionPreparationStatus, ExecuteProtocolInput } from '@heybox/hb-sdk-protocol';
+export { AccountState, AuthorizedUserInfo, CompanionCapability, CompanionExit, CompanionInfo, CompanionNotificationCategory, CompanionPreparationStatus, CompanionPrepareProgress, CompanionTarget, ExecuteProtocolInput, ExecuteProtocolObject, ExecuteProtocolResult, GameSaveStructuredData, MiniProgramDisplayState, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramOperatingSystemName, MiniProgramOrientationMode, MiniProgramRuntimeMode, MiniProgramUserInfoResult, SetDisplayPayload, SetDisplayResult, USER_INFO_AUTHORIZATION_SCOPES, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, WorkspaceCardLaunchContext, WorkspaceCardsRefreshOptions } from '@heybox/hb-sdk-protocol';
 
 /**
  * 小程序生命周期或业务事件监听函数。
@@ -3973,6 +3973,79 @@ interface WorkspaceCardsModule {
     onLaunchContextChange(listener: (context: WorkspaceCardLaunchContext | null) => void): () => void;
 }
 
+/** 文件对象已绑定查询时的游戏、账号、存档和文件，只需指定取消信号。 */
+interface GameSavesFileOptions {
+    signal?: AbortSignal;
+}
+/** list 返回的存档文件；元数据不会触发下载，调用 downloadFile 后才下载。 */
+interface GameSaveFileInfo extends Readonly<GameSaveFileInfo$1> {
+    /**
+     * 下载并返回只读 ZIP 文件，可通过 readBytes() 交给开发者解压和解析。
+     * 无需传入游戏、账号、存档或文件 ID，也不能通过修改元数据改变下载目标。
+     * 单文件最多 8 MiB；当前会话和授权失效后，已有句柄不可读。
+     */
+    downloadFile(options?: GameSavesFileOptions): Promise<FileHandle>;
+}
+interface GameSaveInfo extends Omit<GameSaveInfo$1, 'files'> {
+    files: GameSaveFileInfo[];
+}
+/** 同步由 Runtime 等待至终态；取消仅停止等待，不撤销已经创建的服务端任务。 */
+interface GameSavesSyncOptions {
+    signal?: AbortSignal;
+}
+/** 游戏存档；需声明 gameSaves，无需单独弹窗确认，服务端校验当前账号及存档归属。 */
+interface GameSavesModule {
+    /** 查询指定 Steam 游戏的新版云同步存档；没有存档时返回空数组。
+     * @remarks
+     * 需要配套 H5/Runtime 和后端；复用已有客户端账号及网络能力，不新增客户端版本门槛。
+     * 运行环境缺少所需能力时会拒绝调用；文件下载另需宿主支持文件与传输能力。
+     * @since 0.9.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
+     */
+    list(gameId: string): Promise<GameSaveInfo[]>;
+    /** 读取当前 Steam 账号最新已有的完整结构化业务数据，不对应某个存档批次或 ZIP。
+     * @remarks 读取已保存的数据，不触发更新；无需先查询或同步文件。
+     * @since 0.9.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
+     */
+    getLatestStructuredData(gameId: string): Promise<GameSaveStructuredData>;
+    /** 同步当前绑定 Steam 账号的最新存档并等待成功；无需先调用 list。失败会抛出业务错误，最多等待 5 分钟。
+     * @remarks
+     * 需要配套 H5/Runtime 和后端；复用已有客户端账号及网络能力，不新增客户端版本门槛。
+     * 运行环境缺少所需能力时会拒绝调用；文件下载另需宿主支持文件与传输能力。
+     * @since 0.9.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
+     */
+    sync(gameId: string, options?: GameSavesSyncOptions): Promise<void>;
+}
+
 /**
  * 排行榜排序方向。
  *
@@ -7829,6 +7902,8 @@ declare const device: MiniProgramDeviceModule;
 /** 默认 SDK 实例的 navigation 模块。 */
 declare const navigation: MiniProgramNavigationModule;
 /** 默认 SDK 实例的 cloud 模块。 */
+/** 当前用户的游戏存档能力。 */
+declare const gameSaves: GameSavesModule;
 declare const cloud: MiniProgramCloudModule;
 /** 默认 SDK 实例的受管桌面程序模块。 */
 declare const companion: MiniProgramCompanionModule;
@@ -7855,9 +7930,10 @@ declare const hbSDK: {
     environment: MiniProgramEnvironmentModule;
     navigation: MiniProgramNavigationModule;
     cloud: MiniProgramCloudModule;
+    gameSaves: GameSavesModule;
     companion: MiniProgramCompanionModule;
     workspaceCards: WorkspaceCardsModule;
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, auth, cloud, companion, hbSDK as default, device, environment, files, getHandshakeState, media, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };
-export type { ClosePayload, CloseResult, CompanionAttachments, CompanionExitHandler, CompanionNotification, CompanionNotifications, CompanionOutputHandler, CompanionOwnershipLostHandler, CompanionPrepareOptions, CompanionSession, CompanionState, CompanionStateChangeHandler, CompanionStdio, CopyLinkPayload, CopyLinkResult, CreateOptions, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, ListOptions, LoginOptions, LoginPayload, LoginResult, LoginScope, MediaImageItem, MediaItem, MediaModule, MediaSelectionType, MediaType, MediaVideoItem, MiniProgramAppPageTarget, MiniProgramAuthModule, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, MiniProgramCloudStorageModule, MiniProgramCompanionModule, MiniProgramCopyLinkOptions, MiniProgramDeviceModule, MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramEventHandler, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationModule, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler, MiniProgramSafeArea, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramSetNavigationBarStyleOptions, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, MiniProgramStorageModule, MiniProgramToastStatus, MiniProgramUiModule, MiniProgramUserModule, MiniProgramVibrateIntensity, MiniProgramViewportModule, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPageOptions, OpenGameDetailAppPagePayload, OpenMiniProgramAppPageOptions, OpenMiniProgramAppPagePayload, OpenPostDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenUserDetailAppPageOptions, OpenUserDetailAppPagePayload, PathRoot, PickDirectoryOptions, PickFilesOptions, PickMediaOptions, ReloadPayload, ReloadResult, RemoveOptions, RevokeAuthorizationPayload, RevokeAuthorizationResult, SaveFileOptions, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UploadBaseOptions, UploadOptions, UploadProgress, UploadResponse, VibratePayload, VibrateResult, WorkspaceCardsModule };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, auth, cloud, companion, hbSDK as default, device, environment, files, gameSaves, getHandshakeState, media, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };
+export type { ClosePayload, CloseResult, CompanionAttachments, CompanionExitHandler, CompanionNotification, CompanionNotifications, CompanionOutputHandler, CompanionOwnershipLostHandler, CompanionPrepareOptions, CompanionSession, CompanionState, CompanionStateChangeHandler, CompanionStdio, CopyLinkPayload, CopyLinkResult, CreateOptions, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GameSaveFileInfo, GameSaveInfo, GameSavesFileOptions, GameSavesModule, GameSavesSyncOptions, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, ListOptions, LoginOptions, LoginPayload, LoginResult, LoginScope, MediaImageItem, MediaItem, MediaModule, MediaSelectionType, MediaType, MediaVideoItem, MiniProgramAppPageTarget, MiniProgramAuthModule, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, MiniProgramCloudStorageModule, MiniProgramCompanionModule, MiniProgramCopyLinkOptions, MiniProgramDeviceModule, MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramEventHandler, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationModule, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler, MiniProgramSafeArea, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramSetNavigationBarStyleOptions, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, MiniProgramStorageModule, MiniProgramToastStatus, MiniProgramUiModule, MiniProgramUserModule, MiniProgramVibrateIntensity, MiniProgramViewportModule, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPageOptions, OpenGameDetailAppPagePayload, OpenMiniProgramAppPageOptions, OpenMiniProgramAppPagePayload, OpenPostDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenUserDetailAppPageOptions, OpenUserDetailAppPagePayload, PathRoot, PickDirectoryOptions, PickFilesOptions, PickMediaOptions, ReloadPayload, ReloadResult, RemoveOptions, RevokeAuthorizationPayload, RevokeAuthorizationResult, SaveFileOptions, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UploadBaseOptions, UploadOptions, UploadProgress, UploadResponse, VibratePayload, VibrateResult, WorkspaceCardsModule };

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

@@ -222,7 +222,7 @@ declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
     window?: MiniappWindowDeclaration | undefined;
     workspaceCards?: WorkspaceCardsManifest | undefined;
     companions?: MiniappCompanionManifestDeclarations | undefined;
-    permissions?: Partial<Record<"storage" | "workspaceCards" | "userInfo" | "steamLibrary" | "share" | "cloud_storage" | "filesystem" | "media" | "clipboard" | "leaderboard" | "companion" | "appProtocol", SimpleMiniappPermissionDeclaration> & {
+    permissions?: Partial<Record<"storage" | "workspaceCards" | "userInfo" | "steamLibrary" | "share" | "cloud_storage" | "gameSaves" | "filesystem" | "media" | "clipboard" | "leaderboard" | "companion" | "appProtocol", SimpleMiniappPermissionDeclaration> & {
         network: NetworkMiniappPermissionDeclaration;
     }> | undefined;
     platforms: readonly ("windows" | "macos" | "android" | "ios" | "ohos" | "linux")[];