@heybox/hb-sdk-protocol 0.8.0-alpha.3 → 0.8.0

package/types/capabilities.d.ts

@@ -1,4 +1,5 @@
 import type { ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetStoragePayload, GetStorageResult, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LoginPayload, LoginResult, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ReloadPayload, ReloadResult, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, VibratePayload, VibrateResult } from './payloads';
+import type { MiniProgramPermissionRequirement } from './permission-catalog';
 export declare const AUTH_LOGIN_METHOD: "auth.login";
 export declare const USER_GET_INFO_METHOD: "user.getInfo";
 export declare const USER_REVOKE_AUTHORIZATION_METHOD: "user.revokeAuthorization";
@@ -60,254 +61,367 @@ export interface MiniProgramCapabilityDefinition {
     method: MiniProgramBridgeMethod;
     module: MiniProgramCapabilityModule;
     capability: MiniProgramBridgeMethod;
-    permission: string;
+    requirement: MiniProgramPermissionRequirement;
     risk: MiniProgramCapabilityRisk;
 }
 export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
     readonly method: "auth.login";
     readonly module: "auth";
     readonly capability: "auth.login";
-    readonly permission: "auth.login";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["userInfo"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "user.getInfo";
     readonly module: "user";
     readonly capability: "user.getInfo";
-    readonly permission: "user.getInfo";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["userInfo"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "user.revokeAuthorization";
     readonly module: "user";
     readonly capability: "user.revokeAuthorization";
-    readonly permission: "user.revokeAuthorization";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "high";
 }, {
     readonly method: "user.getSteamGameList";
     readonly module: "user";
     readonly capability: "user.getSteamGameList";
-    readonly permission: "user.platformAccount.steam";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["steamLibrary"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "share.copyLink";
     readonly module: "share";
     readonly capability: "share.copyLink";
-    readonly permission: "share.copyLink";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["share"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "share.showShareMenu";
     readonly module: "share";
     readonly capability: "share.showShareMenu";
-    readonly permission: "share.basic";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["share"];
+    };
     readonly risk: "low";
 }, {
     readonly method: "share.screenshot";
     readonly module: "share";
     readonly capability: "share.screenshot";
-    readonly permission: "share.screenshot";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["share"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "viewport.getWindowInfo";
     readonly module: "viewport";
     readonly capability: "viewport.getWindowInfo";
-    readonly permission: "viewport.windowInfo";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "viewport.setNavigationBarStyle";
     readonly module: "viewport";
     readonly capability: "viewport.setNavigationBarStyle";
-    readonly permission: "viewport.navigationBarStyle";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "storage.getStorage";
     readonly module: "storage";
     readonly capability: "storage.getStorage";
-    readonly permission: "storage.read";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["storage"];
+    };
     readonly risk: "low";
 }, {
     readonly method: "storage.setStorage";
     readonly module: "storage";
     readonly capability: "storage.setStorage";
-    readonly permission: "storage.write";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["storage"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "network.request";
     readonly module: "network";
     readonly capability: "network.request";
-    readonly permission: "network.request";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["network"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "network.download";
     readonly module: "network";
     readonly capability: "network.download";
-    readonly permission: "network.request";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["network", "filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "files.pickFiles";
     readonly module: "files";
     readonly capability: "files.pickFiles";
-    readonly permission: "files.external";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "files.pickDirectory";
     readonly module: "files";
     readonly capability: "files.pickDirectory";
-    readonly permission: "files.external";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "files.saveFile";
     readonly module: "files";
     readonly capability: "files.saveFile";
-    readonly permission: "files.external";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.create";
     readonly module: "file";
     readonly capability: "file.create";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.remove";
     readonly module: "file";
     readonly capability: "file.remove";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.exists";
     readonly module: "file";
     readonly capability: "file.exists";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.readText";
     readonly module: "file";
     readonly capability: "file.readText";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.writeText";
     readonly module: "file";
     readonly capability: "file.writeText";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.readBytes";
     readonly module: "file";
     readonly capability: "file.readBytes";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.writeBytes";
     readonly module: "file";
     readonly capability: "file.writeBytes";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "file.stat";
     readonly module: "file";
     readonly capability: "file.stat";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "directory.create";
     readonly module: "directory";
     readonly capability: "directory.create";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "directory.remove";
     readonly module: "directory";
     readonly capability: "directory.remove";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "directory.exists";
     readonly module: "directory";
     readonly capability: "directory.exists";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "directory.list";
     readonly module: "directory";
     readonly capability: "directory.list";
-    readonly permission: "files.access";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["filesystem"];
+    };
     readonly risk: "high";
 }, {
     readonly method: "ui.showToast";
     readonly module: "ui";
     readonly capability: "ui.showToast";
-    readonly permission: "ui.toast";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "ui.showLoading";
     readonly module: "ui";
     readonly capability: "ui.showLoading";
-    readonly permission: "ui.loading";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "ui.hideLoading";
     readonly module: "ui";
     readonly capability: "ui.hideLoading";
-    readonly permission: "ui.loading";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "device.vibrate";
     readonly module: "device";
     readonly capability: "device.vibrate";
-    readonly permission: "device.vibrate";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "low";
 }, {
     readonly method: "device.setClipboard";
     readonly module: "device";
     readonly capability: "device.setClipboard";
-    readonly permission: "device.clipboard.write";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["clipboard"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "navigation.close";
     readonly module: "navigation";
     readonly capability: "navigation.close";
-    readonly permission: "navigation.close";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "medium";
 }, {
     readonly method: "navigation.reload";
     readonly module: "navigation";
     readonly capability: "navigation.reload";
-    readonly permission: "navigation.reload";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "medium";
 }, {
     readonly method: "navigation.openAppPage";
     readonly module: "navigation";
     readonly capability: "navigation.openAppPage";
-    readonly permission: "navigation.openAppPage";
+    readonly requirement: {
+        readonly kind: "none";
+    };
     readonly risk: "medium";
 }, {
     readonly method: "cloud.leaderboard.submit";
     readonly module: "cloud";
     readonly capability: "cloud.leaderboard.submit";
-    readonly permission: "cloud.leaderboard.write";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["leaderboard"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "cloud.leaderboard.getList";
     readonly module: "cloud";
     readonly capability: "cloud.leaderboard.getList";
-    readonly permission: "cloud.leaderboard.read";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["leaderboard"];
+    };
     readonly risk: "low";
 }, {
     readonly method: "cloud.leaderboard.getCurrentUserEntry";
     readonly module: "cloud";
     readonly capability: "cloud.leaderboard.getCurrentUserEntry";
-    readonly permission: "cloud.leaderboard.currentUserEntry.read";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["leaderboard"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "cloud.leaderboard.deleteCurrentUserEntry";
     readonly module: "cloud";
     readonly capability: "cloud.leaderboard.deleteCurrentUserEntry";
-    readonly permission: "cloud.leaderboard.currentUserEntry.delete";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["leaderboard"];
+    };
     readonly risk: "medium";
 }, {
     readonly method: "cloud.leaderboard.getInfo";
     readonly module: "cloud";
     readonly capability: "cloud.leaderboard.getInfo";
-    readonly permission: "cloud.leaderboard.info.read";
+    readonly requirement: {
+        readonly kind: "all";
+        readonly permissions: readonly ["leaderboard"];
+    };
     readonly risk: "low";
 }];
 export interface MiniProgramCapabilityPayloadMap {

package/types/index.d.ts

@@ -3,4 +3,5 @@ export * from './capabilities';
 export * from './constants';
 export * from './guards';
 export * from './payloads';
+export * from './permission-catalog';
 export * from './permissions';

package/types/payloads.d.ts

@@ -129,7 +129,6 @@ export interface MiniProgramScreenshotRect {
 export type ShowShareMenuPayload = {
     title: string;
     desc: string;
-    url?: string;
     extra?: unknown;
     imageUrl?: string;
     channel?: MiniProgramShareChannel;

package/types/permission-catalog.d.ts

@@ -0,0 +1,108 @@
+import type { MiniProgramBridgeMethod, MiniProgramCapabilityRisk } from './capabilities';
+export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network"];
+export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
+export type MiniProgramPermissionRequirement = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'all';
+    readonly permissions: readonly MiniProgramPermissionKey[];
+};
+export type MiniProgramPermissionAccess = 'declaration' | 'platform-approval';
+export interface MiniProgramPermissionConfigFieldDefinition {
+    readonly type: 'boolean';
+    readonly required: boolean;
+    readonly default: boolean;
+    readonly description: string;
+}
+export interface MiniProgramPermissionDefinition {
+    readonly key: MiniProgramPermissionKey;
+    readonly name: string;
+    readonly description: string;
+    readonly access: MiniProgramPermissionAccess;
+    readonly risk: MiniProgramCapabilityRisk;
+    readonly config: Readonly<Record<string, MiniProgramPermissionConfigFieldDefinition>>;
+    readonly methods: readonly MiniProgramBridgeMethod[];
+    readonly conditions: readonly string[];
+}
+export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
+    readonly key: "userInfo";
+    readonly name: "用户信息";
+    readonly description: "登录小程序并读取当前用户的授权信息。";
+    readonly access: "declaration";
+    readonly risk: "medium";
+    readonly config: {};
+    readonly methods: readonly ["auth.login", "user.getInfo"];
+    readonly conditions: readonly ["继续执行黑盒登录、用户授权和可信手势规则。"];
+}, {
+    readonly key: "steamLibrary";
+    readonly name: "Steam 游戏库";
+    readonly description: "读取当前用户授权的 Steam 游戏库。";
+    readonly access: "declaration";
+    readonly risk: "high";
+    readonly config: {};
+    readonly methods: readonly ["user.getSteamGameList"];
+    readonly conditions: readonly ["继续执行账号绑定和数据可用性规则。"];
+}, {
+    readonly key: "share";
+    readonly name: "分享";
+    readonly description: "使用小程序分享、分享菜单和截图能力。";
+    readonly access: "declaration";
+    readonly risk: "medium";
+    readonly config: {};
+    readonly methods: readonly ["share.copyLink", "share.showShareMenu", "share.screenshot"];
+    readonly conditions: readonly ["继续执行分享参数校验和 Host 支持检查。"];
+}, {
+    readonly key: "storage";
+    readonly name: "键值存储";
+    readonly description: "读写按小程序隔离的简单键值数据。";
+    readonly access: "declaration";
+    readonly risk: "medium";
+    readonly config: {};
+    readonly methods: readonly ["storage.getStorage", "storage.setStorage"];
+    readonly conditions: readonly ["仅用于简单键值存储，不包含文件系统。"];
+}, {
+    readonly key: "filesystem";
+    readonly name: "文件系统";
+    readonly description: "访问小程序沙盒文件和用户选择的外部文件。";
+    readonly access: "declaration";
+    readonly risk: "high";
+    readonly config: {};
+    readonly methods: readonly ["network.download", "files.pickFiles", "files.pickDirectory", "files.saveFile", "file.create", "file.remove", "file.exists", "file.readText", "file.writeText", "file.readBytes", "file.writeBytes", "file.stat", "directory.create", "directory.remove", "directory.exists", "directory.list"];
+    readonly conditions: readonly ["外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。"];
+}, {
+    readonly key: "clipboard";
+    readonly name: "剪贴板";
+    readonly description: "向系统剪贴板写入文本。";
+    readonly access: "declaration";
+    readonly risk: "medium";
+    readonly config: {};
+    readonly methods: readonly ["device.setClipboard"];
+    readonly conditions: readonly ["继续执行文本长度和 Host 支持限制。"];
+}, {
+    readonly key: "leaderboard";
+    readonly name: "排行榜";
+    readonly description: "读写小程序云排行榜。";
+    readonly access: "declaration";
+    readonly risk: "medium";
+    readonly config: {};
+    readonly methods: readonly ["cloud.leaderboard.submit", "cloud.leaderboard.getList", "cloud.leaderboard.getCurrentUserEntry", "cloud.leaderboard.deleteCurrentUserEntry", "cloud.leaderboard.getInfo"];
+    readonly conditions: readonly ["排行榜必须已创建，用户和资源规则保持不变。"];
+}, {
+    readonly key: "network";
+    readonly name: "网络";
+    readonly description: "通过 network 模块请求或下载外部资源。";
+    readonly access: "platform-approval";
+    readonly risk: "high";
+    readonly config: {
+        readonly useOfficialDomain: {
+            readonly type: "boolean";
+            readonly required: false;
+            readonly default: false;
+            readonly description: "是否申请访问小黑盒官方域名。";
+        };
+    };
+    readonly methods: readonly ["network.request", "network.download"];
+    readonly conditions: readonly ["声明后仍需平台批准，并继续执行网络安全策略。"];
+}];
+export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
+export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;

package/types/permissions.d.ts

@@ -1,7 +1,8 @@
-export declare function isManagedMiniProgramRuntimePermissionKey(key: string): boolean;
+import { type MiniProgramPermissionKey } from './permission-catalog';
+export declare function isManagedMiniProgramRuntimePermissionKey(key: string): key is MiniProgramPermissionKey;
 export type MiniProgramRuntimePermissionStatus = 'enabled' | 'disabled';
 export interface MiniProgramRuntimePermissionEntry {
-    key: string;
+    key: MiniProgramPermissionKey;
     status: MiniProgramRuntimePermissionStatus;
     config: Record<string, unknown>;
 }
@@ -12,6 +13,6 @@ export interface MiniProgramRuntimePermissionsSnapshot {
 }
 export interface ParsedMiniProgramRuntimePermissions {
     valid: boolean;
-    permissions: Record<string, MiniProgramRuntimePermissionEntry>;
+    permissions: Partial<Record<MiniProgramPermissionKey, MiniProgramRuntimePermissionEntry>>;
 }
 export declare function parseMiniProgramRuntimePermissions(snapshot: unknown): ParsedMiniProgramRuntimePermissions;