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

package/src/bridge.ts

@@ -1,7 +1,7 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE } from './constants';
-import type { UserInfoAuthorization } from './payloads';
+import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
+import type { DownloadProgressPayload, UserInfoAuthorization } from './payloads';
 
-export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event';
+export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName =
   | 'launch'
   | 'ready'
@@ -56,6 +56,24 @@ export interface MiniProgramBridgeMessage<TPayload = unknown> {
   payload?: TPayload;
   error?: MiniProgramBridgeError;
 }
+
+export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage<never> {
+  version: 2;
+  type: 'cancel';
+  id: string;
+  method?: never;
+  payload?: never;
+  error?: never;
+}
+
+export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+  version: 2;
+  type: 'event';
+  id: string;
+  method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
+  payload: DownloadProgressPayload;
+  error?: never;
+}
 export interface MiniProgramEventPayloadMap {
   launch: { timestamp: number; url?: string };
   ready: { timestamp: number };

package/src/capabilities.ts

@@ -3,6 +3,14 @@ import type {
   CloseResult,
   CopyLinkPayload,
   CopyLinkResult,
+  DirectoryCreatePayload,
+  DirectoryCreateResult,
+  DirectoryExistsPayload,
+  DirectoryExistsResult,
+  DirectoryListPayload,
+  DirectoryListResult,
+  DirectoryRemovePayload,
+  DirectoryRemoveResult,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -21,16 +29,40 @@ import type {
   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,
@@ -47,6 +79,7 @@ import type {
   VibratePayload,
   VibrateResult,
 } from './payloads';
+import type { MiniProgramPermissionRequirement } from './permission-catalog';
 
 export const AUTH_LOGIN_METHOD = 'auth.login' as const;
 export const USER_GET_INFO_METHOD = 'user.getInfo' as const;
@@ -60,6 +93,22 @@ export const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationB
 export const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage' as const;
 export const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage' as const;
 export const NETWORK_REQUEST_METHOD = 'network.request' as const;
+export const NETWORK_DOWNLOAD_METHOD = 'network.download' as const;
+export const FILES_PICK_FILES_METHOD = 'files.pickFiles' as const;
+export const FILES_PICK_DIRECTORY_METHOD = 'files.pickDirectory' as const;
+export const FILES_SAVE_FILE_METHOD = 'files.saveFile' as const;
+export const FILE_CREATE_METHOD = 'file.create' as const;
+export const FILE_REMOVE_METHOD = 'file.remove' as const;
+export const FILE_EXISTS_METHOD = 'file.exists' as const;
+export const FILE_READ_TEXT_METHOD = 'file.readText' as const;
+export const FILE_WRITE_TEXT_METHOD = 'file.writeText' as const;
+export const FILE_READ_BYTES_METHOD = 'file.readBytes' as const;
+export const FILE_WRITE_BYTES_METHOD = 'file.writeBytes' as const;
+export const FILE_STAT_METHOD = 'file.stat' as const;
+export const DIRECTORY_CREATE_METHOD = 'directory.create' as const;
+export const DIRECTORY_REMOVE_METHOD = 'directory.remove' as const;
+export const DIRECTORY_EXISTS_METHOD = 'directory.exists' as const;
+export const DIRECTORY_LIST_METHOD = 'directory.list' as const;
 export const UI_SHOW_TOAST_METHOD = 'ui.showToast' as const;
 export const UI_SHOW_LOADING_METHOD = 'ui.showLoading' as const;
 export const UI_HIDE_LOADING_METHOD = 'ui.hideLoading' as const;
@@ -79,7 +128,22 @@ export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_RE
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
 export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD | typeof VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
 export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
-export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD;
+export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD | typeof NETWORK_DOWNLOAD_METHOD;
+export type MiniProgramFilesMethod = typeof FILES_PICK_FILES_METHOD | typeof FILES_PICK_DIRECTORY_METHOD | typeof FILES_SAVE_FILE_METHOD;
+export type MiniProgramFileMethod =
+  | typeof FILE_CREATE_METHOD
+  | typeof FILE_REMOVE_METHOD
+  | typeof FILE_EXISTS_METHOD
+  | typeof FILE_READ_TEXT_METHOD
+  | typeof FILE_WRITE_TEXT_METHOD
+  | typeof FILE_READ_BYTES_METHOD
+  | typeof FILE_WRITE_BYTES_METHOD
+  | typeof FILE_STAT_METHOD;
+export type MiniProgramDirectoryMethod =
+  | typeof DIRECTORY_CREATE_METHOD
+  | typeof DIRECTORY_REMOVE_METHOD
+  | typeof DIRECTORY_EXISTS_METHOD
+  | typeof DIRECTORY_LIST_METHOD;
 export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_LOADING_METHOD | typeof UI_HIDE_LOADING_METHOD;
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
@@ -96,111 +160,281 @@ export type MiniProgramBridgeMethod =
   | MiniProgramViewportMethod
   | MiniProgramStorageMethod
   | MiniProgramNetworkMethod
+  | MiniProgramFilesMethod
+  | MiniProgramFileMethod
+  | MiniProgramDirectoryMethod
   | MiniProgramUiMethod
   | MiniProgramDeviceMethod
   | MiniProgramNavigationMethod
   | MiniProgramCloudMethod;
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation' | 'cloud';
+export type MiniProgramCapabilityModule =
+  | 'auth'
+  | 'user'
+  | 'share'
+  | 'viewport'
+  | 'storage'
+  | 'network'
+  | 'files'
+  | 'file'
+  | 'directory'
+  | 'ui'
+  | 'device'
+  | 'navigation'
+  | 'cloud';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 
 export interface MiniProgramCapabilityDefinition {
   method: MiniProgramBridgeMethod;
   module: MiniProgramCapabilityModule;
   capability: MiniProgramBridgeMethod;
-  permission: string;
+  requirement: MiniProgramPermissionRequirement;
   risk: MiniProgramCapabilityRisk;
 }
 
 export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
-  { method: AUTH_LOGIN_METHOD, module: 'auth', capability: AUTH_LOGIN_METHOD, permission: 'auth.login', risk: 'medium' },
-  { method: USER_GET_INFO_METHOD, module: 'user', capability: USER_GET_INFO_METHOD, permission: 'user.getInfo', risk: 'medium' },
+  {
+    method: AUTH_LOGIN_METHOD,
+    module: 'auth',
+    capability: AUTH_LOGIN_METHOD,
+    requirement: { kind: 'all', permissions: ['userInfo'] },
+    risk: 'medium',
+  },
+  {
+    method: USER_GET_INFO_METHOD,
+    module: 'user',
+    capability: USER_GET_INFO_METHOD,
+    requirement: { kind: 'all', permissions: ['userInfo'] },
+    risk: 'medium',
+  },
   {
     method: USER_REVOKE_AUTHORIZATION_METHOD,
     module: 'user',
     capability: USER_REVOKE_AUTHORIZATION_METHOD,
-    permission: 'user.revokeAuthorization',
+    requirement: { kind: 'none' },
     risk: 'high',
   },
   {
     method: USER_GET_STEAM_GAME_LIST_METHOD,
     module: 'user',
     capability: USER_GET_STEAM_GAME_LIST_METHOD,
-    permission: 'user.platformAccount.steam',
+    requirement: { kind: 'all', permissions: ['steamLibrary'] },
     risk: 'high',
   },
-  { method: SHARE_COPY_LINK_METHOD, module: 'share', capability: SHARE_COPY_LINK_METHOD, permission: 'share.copyLink', risk: 'medium' },
-  { method: SHARE_SHOW_SHARE_MENU_METHOD, module: 'share', capability: SHARE_SHOW_SHARE_MENU_METHOD, permission: 'share.basic', risk: 'low' },
-  { method: SHARE_SCREENSHOT_METHOD, module: 'share', capability: SHARE_SCREENSHOT_METHOD, permission: 'share.screenshot', risk: 'medium' },
+  {
+    method: SHARE_COPY_LINK_METHOD,
+    module: 'share',
+    capability: SHARE_COPY_LINK_METHOD,
+    requirement: { kind: 'all', permissions: ['share'] },
+    risk: 'medium',
+  },
+  {
+    method: SHARE_SHOW_SHARE_MENU_METHOD,
+    module: 'share',
+    capability: SHARE_SHOW_SHARE_MENU_METHOD,
+    requirement: { kind: 'all', permissions: ['share'] },
+    risk: 'low',
+  },
+  {
+    method: SHARE_SCREENSHOT_METHOD,
+    module: 'share',
+    capability: SHARE_SCREENSHOT_METHOD,
+    requirement: { kind: 'all', permissions: ['share'] },
+    risk: 'medium',
+  },
   {
     method: VIEWPORT_GET_WINDOW_INFO_METHOD,
     module: 'viewport',
     capability: VIEWPORT_GET_WINDOW_INFO_METHOD,
-    permission: 'viewport.windowInfo',
+    requirement: { kind: 'none' },
     risk: 'low',
   },
   {
     method: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
     module: 'viewport',
     capability: VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
-    permission: 'viewport.navigationBarStyle',
+    requirement: { kind: 'none' },
     risk: 'low',
   },
-  { method: STORAGE_GET_STORAGE_METHOD, module: 'storage', capability: STORAGE_GET_STORAGE_METHOD, permission: 'storage.read', risk: 'low' },
-  { method: STORAGE_SET_STORAGE_METHOD, module: 'storage', capability: STORAGE_SET_STORAGE_METHOD, permission: 'storage.write', risk: 'medium' },
-  { method: NETWORK_REQUEST_METHOD, module: 'network', capability: NETWORK_REQUEST_METHOD, permission: 'network.request', risk: 'high' },
-  { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, permission: 'ui.toast', risk: 'low' },
-  { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
-  { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
-  { method: DEVICE_VIBRATE_METHOD, module: 'device', capability: DEVICE_VIBRATE_METHOD, permission: 'device.vibrate', risk: 'low' },
+  {
+    method: STORAGE_GET_STORAGE_METHOD,
+    module: 'storage',
+    capability: STORAGE_GET_STORAGE_METHOD,
+    requirement: { kind: 'all', permissions: ['storage'] },
+    risk: 'low',
+  },
+  {
+    method: STORAGE_SET_STORAGE_METHOD,
+    module: 'storage',
+    capability: STORAGE_SET_STORAGE_METHOD,
+    requirement: { kind: 'all', permissions: ['storage'] },
+    risk: 'medium',
+  },
+  {
+    method: NETWORK_REQUEST_METHOD,
+    module: 'network',
+    capability: NETWORK_REQUEST_METHOD,
+    requirement: { kind: 'all', permissions: ['network'] },
+    risk: 'high',
+  },
+  {
+    method: NETWORK_DOWNLOAD_METHOD,
+    module: 'network',
+    capability: NETWORK_DOWNLOAD_METHOD,
+    requirement: { kind: 'all', permissions: ['network', 'filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILES_PICK_FILES_METHOD,
+    module: 'files',
+    capability: FILES_PICK_FILES_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILES_PICK_DIRECTORY_METHOD,
+    module: 'files',
+    capability: FILES_PICK_DIRECTORY_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILES_SAVE_FILE_METHOD,
+    module: 'files',
+    capability: FILES_SAVE_FILE_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_CREATE_METHOD,
+    module: 'file',
+    capability: FILE_CREATE_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_REMOVE_METHOD,
+    module: 'file',
+    capability: FILE_REMOVE_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_EXISTS_METHOD,
+    module: 'file',
+    capability: FILE_EXISTS_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_READ_TEXT_METHOD,
+    module: 'file',
+    capability: FILE_READ_TEXT_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_WRITE_TEXT_METHOD,
+    module: 'file',
+    capability: FILE_WRITE_TEXT_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_READ_BYTES_METHOD,
+    module: 'file',
+    capability: FILE_READ_BYTES_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: FILE_WRITE_BYTES_METHOD,
+    module: 'file',
+    capability: FILE_WRITE_BYTES_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  { method: FILE_STAT_METHOD, module: 'file', capability: FILE_STAT_METHOD, requirement: { kind: 'all', permissions: ['filesystem'] }, risk: 'high' },
+  {
+    method: DIRECTORY_CREATE_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_CREATE_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: DIRECTORY_REMOVE_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_REMOVE_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: DIRECTORY_EXISTS_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_EXISTS_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  {
+    method: DIRECTORY_LIST_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_LIST_METHOD,
+    requirement: { kind: 'all', permissions: ['filesystem'] },
+    risk: 'high',
+  },
+  { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, requirement: { kind: 'none' }, risk: 'low' },
+  { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
+  { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
+  { method: DEVICE_VIBRATE_METHOD, module: 'device', capability: DEVICE_VIBRATE_METHOD, requirement: { kind: 'none' }, risk: 'low' },
   {
     method: DEVICE_SET_CLIPBOARD_METHOD,
     module: 'device',
     capability: DEVICE_SET_CLIPBOARD_METHOD,
-    permission: 'device.clipboard.write',
+    requirement: { kind: 'all', permissions: ['clipboard'] },
     risk: 'medium',
   },
-  { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, permission: 'navigation.close', risk: 'medium' },
-  { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, permission: 'navigation.reload', risk: 'medium' },
+  { method: NAVIGATION_CLOSE_METHOD, module: 'navigation', capability: NAVIGATION_CLOSE_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
+  { method: NAVIGATION_RELOAD_METHOD, module: 'navigation', capability: NAVIGATION_RELOAD_METHOD, requirement: { kind: 'none' }, risk: 'medium' },
   {
     method: NAVIGATION_OPEN_APP_PAGE_METHOD,
     module: 'navigation',
     capability: NAVIGATION_OPEN_APP_PAGE_METHOD,
-    permission: 'navigation.openAppPage',
+    requirement: { kind: 'none' },
     risk: 'medium',
   },
   {
     method: CLOUD_LEADERBOARD_SUBMIT_METHOD,
     module: 'cloud',
     capability: CLOUD_LEADERBOARD_SUBMIT_METHOD,
-    permission: 'cloud.leaderboard.write',
+    requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'medium',
   },
   {
     method: CLOUD_LEADERBOARD_GET_LIST_METHOD,
     module: 'cloud',
     capability: CLOUD_LEADERBOARD_GET_LIST_METHOD,
-    permission: 'cloud.leaderboard.read',
+    requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'low',
   },
   {
     method: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
     module: 'cloud',
     capability: CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD,
-    permission: 'cloud.leaderboard.currentUserEntry.read',
+    requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'medium',
   },
   {
     method: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
     module: 'cloud',
     capability: CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD,
-    permission: 'cloud.leaderboard.currentUserEntry.delete',
+    requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'medium',
   },
   {
     method: CLOUD_LEADERBOARD_GET_INFO_METHOD,
     module: 'cloud',
     capability: CLOUD_LEADERBOARD_GET_INFO_METHOD,
-    permission: 'cloud.leaderboard.info.read',
+    requirement: { kind: 'all', permissions: ['leaderboard'] },
     risk: 'low',
   },
 ] as const satisfies readonly MiniProgramCapabilityDefinition[];
@@ -218,6 +452,22 @@ export interface MiniProgramCapabilityPayloadMap {
   [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
   [STORAGE_SET_STORAGE_METHOD]: SetStoragePayload;
   [NETWORK_REQUEST_METHOD]: NetworkRequestPayload;
+  [NETWORK_DOWNLOAD_METHOD]: NetworkDownloadPayload;
+  [FILES_PICK_FILES_METHOD]: PickFilesPayload;
+  [FILES_PICK_DIRECTORY_METHOD]: PickDirectoryPayload;
+  [FILES_SAVE_FILE_METHOD]: SaveFilePayload;
+  [FILE_CREATE_METHOD]: FileCreatePayload;
+  [FILE_REMOVE_METHOD]: FileRemovePayload;
+  [FILE_EXISTS_METHOD]: FileExistsPayload;
+  [FILE_READ_TEXT_METHOD]: FileReadTextPayload;
+  [FILE_WRITE_TEXT_METHOD]: FileWriteTextPayload;
+  [FILE_READ_BYTES_METHOD]: FileReadBytesPayload;
+  [FILE_WRITE_BYTES_METHOD]: FileWriteBytesPayload;
+  [FILE_STAT_METHOD]: FileStatPayload;
+  [DIRECTORY_CREATE_METHOD]: DirectoryCreatePayload;
+  [DIRECTORY_REMOVE_METHOD]: DirectoryRemovePayload;
+  [DIRECTORY_EXISTS_METHOD]: DirectoryExistsPayload;
+  [DIRECTORY_LIST_METHOD]: DirectoryListPayload;
   [UI_SHOW_TOAST_METHOD]: ShowToastPayload;
   [UI_SHOW_LOADING_METHOD]: ShowLoadingPayload;
   [UI_HIDE_LOADING_METHOD]: HideLoadingPayload;
@@ -246,6 +496,22 @@ export interface MiniProgramCapabilityResultMap {
   [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;
   [STORAGE_SET_STORAGE_METHOD]: void;
   [NETWORK_REQUEST_METHOD]: NetworkResponsePayload;
+  [NETWORK_DOWNLOAD_METHOD]: NetworkDownloadResult;
+  [FILES_PICK_FILES_METHOD]: PickFilesResult;
+  [FILES_PICK_DIRECTORY_METHOD]: PickDirectoryResult;
+  [FILES_SAVE_FILE_METHOD]: SaveFileResult;
+  [FILE_CREATE_METHOD]: FileCreateResult;
+  [FILE_REMOVE_METHOD]: FileRemoveResult;
+  [FILE_EXISTS_METHOD]: FileExistsResult;
+  [FILE_READ_TEXT_METHOD]: FileReadTextResult;
+  [FILE_WRITE_TEXT_METHOD]: FileWriteTextResult;
+  [FILE_READ_BYTES_METHOD]: FileReadBytesResult;
+  [FILE_WRITE_BYTES_METHOD]: FileWriteBytesResult;
+  [FILE_STAT_METHOD]: FileStatResult;
+  [DIRECTORY_CREATE_METHOD]: DirectoryCreateResult;
+  [DIRECTORY_REMOVE_METHOD]: DirectoryRemoveResult;
+  [DIRECTORY_EXISTS_METHOD]: DirectoryExistsResult;
+  [DIRECTORY_LIST_METHOD]: DirectoryListResult;
   [UI_SHOW_TOAST_METHOD]: ShowToastResult;
   [UI_SHOW_LOADING_METHOD]: ShowLoadingResult;
   [UI_HIDE_LOADING_METHOD]: HideLoadingResult;

package/src/constants.ts

@@ -5,3 +5,4 @@ export const SDK_HANDSHAKE_METHOD = 'sdk.handshake' as const;
 export const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe' as const;
 export const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report' as const;
 export const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation' as const;
+export const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress' as const;

package/src/guards.ts

@@ -1,13 +1,167 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE } from './constants';
+import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, SDK_HANDSHAKE_METHOD } from './constants';
 import type { MiniProgramBridgeMessage } from './bridge';
+import type {
+  DownloadProgressPayload,
+  MiniProgramDirectoryDescriptor,
+  MiniProgramDirectoryRef,
+  MiniProgramFileDescriptor,
+  MiniProgramFileRef,
+  MiniProgramFileStat,
+  MiniProgramFileSystemEntityDescriptor,
+  MiniProgramPathRootRef,
+} from './payloads';
 
 export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage {
-  if (!value || typeof value !== 'object') return false;
-  const message = value as Partial<MiniProgramBridgeMessage>;
+  if (!isRecord(value)) return false;
+  if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    return false;
+  }
+
+  if (value.type === 'handshake') {
+    return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+  }
+  if (value.type === 'request') {
+    return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+  }
+  if (value.type === 'response') {
+    return (
+      isNonEmptyString(value.id) &&
+      (value.method === undefined || isNonEmptyString(value.method)) &&
+      (value.error === undefined || isBridgeError(value.error))
+    );
+  }
+  if (value.type === 'event') {
+    if (!isNonEmptyString(value.method) || value.error !== undefined) return false;
+    if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
+      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+    }
+    return value.id === undefined || isNonEmptyString(value.id);
+  }
+  if (value.type === 'cancel') {
+    return (
+      value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined
+    );
+  }
+  return false;
+}
+
+export function isMiniProgramRelativePath(value: unknown): value is string {
+  if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
+    return false;
+  }
+  if (/[\\\u0000-\u001f\u007f]/.test(value)) return false;
+  return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
+}
+
+export function isMiniProgramPathRootRef(value: unknown): value is MiniProgramPathRootRef {
+  if (!isRecord(value)) return false;
+  if (value.kind === 'sandbox') return hasOnlyKeys(value, ['kind']);
+  return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+}
+
+export function isMiniProgramFileRef(value: unknown): value is MiniProgramFileRef {
+  if (!isRecord(value) || value.kind !== 'file') return false;
+  if (isNonEmptyString(value.handleId)) {
+    return hasOnlyKeys(value, ['kind', 'handleId']);
+  }
+  return (
+    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
+  );
+}
+
+export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramDirectoryRef {
+  if (!isRecord(value) || value.kind !== 'directory') return false;
+  if (isNonEmptyString(value.handleId)) {
+    return hasOnlyKeys(value, ['kind', 'handleId']);
+  }
   return (
-    message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
-    (message.version === 1 || message.version === 2) &&
-    typeof message.nonce === 'string' &&
-    typeof message.type === 'string'
+    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
   );
 }
+
+export function isMiniProgramFileDescriptor(value: unknown): value is MiniProgramFileDescriptor {
+  return (
+    isRecord(value) &&
+    value.kind === 'file' &&
+    isNonEmptyString(value.name) &&
+    isFileMode(value.mode) &&
+    isMiniProgramFileRef(value.ref) &&
+    hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref'])
+  );
+}
+
+export function isMiniProgramDirectoryDescriptor(value: unknown): value is MiniProgramDirectoryDescriptor {
+  return (
+    isRecord(value) &&
+    value.kind === 'directory' &&
+    isNonEmptyString(value.name) &&
+    isFileMode(value.mode) &&
+    isMiniProgramDirectoryRef(value.ref) &&
+    hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref'])
+  );
+}
+
+export function isMiniProgramFileSystemEntityDescriptor(value: unknown): value is MiniProgramFileSystemEntityDescriptor {
+  return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
+}
+
+export function isMiniProgramByteArray(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
+}
+
+export function isMiniProgramFileStat(value: unknown): value is MiniProgramFileStat {
+  return (
+    isRecord(value) &&
+    value.kind === 'file' &&
+    isNonNegativeSafeInteger(value.size) &&
+    (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
+    (value.createdAt === undefined || isNonNegativeFiniteNumber(value.createdAt)) &&
+    hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt'])
+  );
+}
+
+export function isMiniProgramDownloadProgressPayload(value: unknown): value is DownloadProgressPayload {
+  if (
+    !isRecord(value) ||
+    !isNonNegativeSafeInteger(value.loaded) ||
+    typeof value.lengthComputable !== 'boolean' ||
+    !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])
+  ) {
+    return false;
+  }
+  if (!value.lengthComputable) return value.total === undefined;
+  return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
+}
+
+function isSDKHandshakePayload(value: unknown) {
+  return isRecord(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+}
+
+function isBridgeError(value: unknown) {
+  return isRecord(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+}
+
+function isFileMode(value: unknown) {
+  return value === 'read' || value === 'readwrite';
+}
+
+function isNonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isNonNegativeFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly string[]) {
+  const allowed = new Set(allowedKeys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}